Server Side Includes (SSI) Primer

Tutorial on how to handle common code, embed CGI output in a web page, etc

Server Side Includes (SSI) Primer

by Christopher Heng,

If you look at the pages on, you'll probably notice that there are a lot of text on each page common with the other pages (such as the logo, the search field, the navigation menu, and so on). Maintaining so many pages with common code or text can be quite a pain when you want to change it. This is where having Server Side Includes (or SSI) on your web server comes in useful. It allows you to put all the common elements into a single file that is automatically included on all your pages.

Who is this Guide For?

This is a primer designed for those who want to get started with using SSI for the situation listed above. It is by no means an exhaustive guide on SSI — I have omitted SSI facilities like setting environment variables, printing the date, etc, in order to focus on the SSI directives most commonly used.

To benefit from this tutorial, you should already know how to create a website as well as how to add raw HTML code into that page. If you use a visual web editor, you can find out how to insert HTML code with Expression Web, Dreamweaver, BlueGriffon and KompoZer in my other tutorials (just click the links in this sentence to get there). Note though that many visual editors do not automatically update your page with the information contained in the SSI directives. You will have to upload it to your site on the Internet to see the results.

What You Need

Before you can use the methods given below, your web host must be an Apache server with Server Side Includes (SSI) enabled. You can probably find out the type of web server your site is on by either reading your web host's documentation or asking them.

How to Include the Contents of Another File

There are a number of reasons why you might want to insert the contents of a file into your web page. As mentioned earlier, one reason may be that you want to put the code or text that is common to all your pages (like your navigation menu) in a single location. That way, when you want to update your (say) menu, you only need to change one file and it will automatically be reflected on all your pages.

First put the stuff you want on every web page into a separate file called, say, "commoncode.txt". Then insert the following line in the web page at the location where you want the contents of "commoncode.txt" dumped:

<!--#include virtual="commoncode.txt" -->

Note that there are no spaces between "<!--" and the "#include" directive.

If you place your file in a subdirectory somewhere, you can use the usual relative path. For example, if your commoncode.txt file is placed in a subdirectory called "common", then your SSI directive will look like the following:

<!--#include virtual="common/commoncode.txt" -->

Note that the directory separator is the forward slash, "/", as in all Unix systems and not the backslash that you may be accustomed to if you come from the Windows world.

You can put anything you like in the commoncode.txt file that you want inserted into your web page at that point. The SSI directive makes it seem as though your web page contained the entire contents of the included file at the location you put the directive. The entire process is transparent to the visitor who visits your site.

Obviously, if you have non-contiguous chunks of code, each of which is to be inserted into differents parts of your web page, you will need to put those chunks into separate files and use the SSI "include" directive to insert each of them into its respective location.

Including the Output of a CGI Script

Sometimes you want to insert the output of a CGI or PHP script into your web page. You might want to do this if, for example, you were running a banner rotation script that generates a different set of HTML code on each invocation.

If your script has the name "banner.cgi" and it is located in your website's cgi-bin subdirectory, the SSI directive would look like the following:

<!--#exec cgi="/cgi-bin/banner.cgi" -->

Some web hosts allow you to execute any program on the server and include its output on your page. If so, and you wish to run (say) the "/bin/ls" command, you would put a directive like the following:

<!--#exec cmd="/bin/ls" -->

You will naturally have to use the correct path for that particular program before it will work as desired.

File Names

Most web hosts that support SSI directives require that the web pages that use them have a ".shtml" extension. This is because SSI processing takes up processor time and the web host does not want their machine to slowed down by having the web server check every single HTML file for SSI directives. As such, if you want your web page's SSI directives to work, you will need to rename it with the appropriate extension. Check with your web host what this extension is (usually ".shtml").

Some free web hosts parse SSI directives for every single HTML file their server delivers, including ".html" files. Even so, you may still want to consider using the ".shtml" extension for new files so that you can easily move to a commercial host in future without the headache of having to rename your files and updating all the links to those pages.

Planning Ahead

Even if you think you do not need to use Server Side Includes (SSI) on your site now, I suggest that you plan ahead.

Take a look at your web site. Is it a site that is likely to expand in number of pages? If you're selling a product and have the product description on its own page, does it seem likely that you will be selling more products in the future? If so, you should start using SSI on your site, even though at this point in time, you probably feel it is unnecessary. You'll think differently once your site expands, and you have to update a few hundred pages each time something changes. At that time, changing your pages to a ".shtml" extension and replacing blocks of common code with SSI directives in all your pages will be much more of a hassle than when your site is smaller.

Copyright 2000-2017 by Christopher Heng. All rights reserved.
Get more free tips and articles like this, on web design, promotion, revenue and scripting, from

thesitewizard™ News Feed (RSS Site Feed)  Subscribe to newsfeed

Do you find this article useful? You can learn of new articles and scripts that are published on by subscribing to the RSS feed. Simply point your RSS feed reader or a browser that supports RSS feeds at You can read more about how to subscribe to RSS site feeds from my RSS FAQ.

Please Do Not Reprint This Article

This article is copyrighted. Please do not reproduce or distribute this article in whole or part, in any form.

Related Pages

New Articles

Popular Articles

How to Link to This Page

It will appear on your page as:

Server Side Includes (SSI) Primer

Link to Us
Site Map

Getting Started
Web Design
Search Engines
Revenue Making
Web Hosting
Perl / CGI
.htaccess / Apache


Free webmasters and programmers resources, scripts and tutorials Free How-To Guides
Site Design Tips at
Find this site useful?
Please link to us.