FAQ: How to Use SSI (Server Side Includes)

By Andreas Ramos. Updated December, 2023

Here's how to use SSI in your website. This assumes you understand how to make a simple website, with perhaps three pages. You know how to link pages together and how to upload them to your website.

First, let's talk about the advantage of using SSI.

Why Use SSI?

Okay, you have your standard website, with an index page and perhaps a dozen subpages. Your site has a set of elements on every page (banner logo at the top, navigation bar on the side, and more navigation elements in a footer at the bottom.) Each page has its unique content. Each page also has elements that appear on every page, and thus these elements are "universal elements."

When you add a new universal element (or modify a universal element,) you have to change it on all pages. Let's say that you add a copyright page. So now you have to open all twelve pages and add a copyright link to the footer of all twelve pages. Next week, you decide to change the copyright year. This means that you will reopen all twelve pages and make the change.

It's okay to do it manually; twelve pages isn't that much. You can do this in maybe twenty minutes.

But your site will grow. Pretty soon, you'll have 200 pages. Any small corporate site will have several hundred pages. My site at Andreas.com has over 1,000 files. Large corporations will have 250,000 pages; some have millions of web pages. It's impossible to manually add (or update) a copyright notice across all pages.

SSI is a solution for this problem. By adding a link which points to a single file that contains the copyright text, your copyright text will appear on all pages.

How to Make an SSI Page

Before you start, visit your ISP's FAQ pages and search for "htaccess." You need to check if your ISP allows you to use htaccess files. If these are not permitted, then you won't be able to use SSI.

The best way to explain this is to create a sample page that uses SSI. You have an index.html page and twelve subpages. Every page has its content. It also has universal elements that exist on all pages: a logo banner at the top, navigation bar on the side (links to page one, page two, and so on,) and a footer with more navigation items (copyright, contact, and so on.) See Andreas.com as an example.

Open your index page's HTML and copy the left-side navigation bar. Copy the entire block.
Open a new blank page and insert the navigation bar. Do not add HTML, HEAD, BODY, or anything else. Just the navigation bar.
Save the new page as navbar.txt. You can name it whatever you like. Tip: I add the prefix ssi-, so I know what these files are (for example, ssi-navbar.txt.) It's up to you.
Do the same for the header banner and the footer text. Copy the HTML into new blank files and save them as ssi-banner.html and ssi-footer.html.
Now go back to the index.html page. At the place where you have the navigation bar, delete the HTML and replace it with the following:



This is an SSI link. When a visitor's browser opens your website, the server will fetch the navbar.txt file, insert it into the HTML, and send the page to your visitor. She will see the navbar in your page, as it should be.
If you named your navbar as links.html, then change the file name in the SSI link into links.html. Just edit it to use the file names that you gave your files.
Note: Don't retype that. Copy and paste it into your index.html and edit it. The spaces, or lack of spaces, is important. If you add or remove a space, it won't work.
Do the same for the rest of your index.html page. Copy the banner HTML code, paste it into a new page named ssi-banner.html, and replace the banner HTML code in the index.html page with the SSI code .
Do the same for the footer HTML code.
If you upload this to your website and open the page on your browser, you'll see that the banner, navbar, and footer are missing. You'll only see the content of your page, but none of the universal elements.

.htaccess File

Before we continue, we need to take a break to add another file to your website.

SSI has a bit of a problem. I didn't tell you that if you use SSI, all files must be renamed filename.shtml, plus all of your links must be renamed to end with the extension shtml.

This can be a major problem. When other users link to your site, they will probably think shtml is a typo. If they use the html extension, the link won't work. Plus, it's a bother for you to rename all of the links and your 100 pages to shtml. Finally, if you have 100,000 pages and 200 people at your company, none of them will remember to always use shtml.

But there's a solution to this. You can use .htaccess to redirect the files. This file is named ".htaccess" (which is pronounced dot-h-t-access). It has no extension.

The htaccess file lets you use .shtml extensions and it reinterprets those as if they were .html extensions. Basically, you say .shtml, but the computer thinks you said .html, so you avoid the file naming problems.

This is like doing the Jedi knight mind trick on the server.

Server: "I am looking for shtml files."
Jedi Knight: "These are the html files you are looking for."
Server: "These are the html files I am looking for."

Now, you can't actually write a .htaccess file on a Windows (or Mac) machine, because these machines won't let you create a file with an extension but no name. So here's how to do this.

Create a text file (use Notepad or BBEdit) and save it as htaccess.txt.
Copy the following line and paste it into the text file:

AddType text/x-server-parsed-html .html
Save the file as htaccess.txt, set your file transfer to ASCII (not binary,) and upload it to your website. Place it in the same folder as your website's index.html file.
Now rename the file on your server. If you're using WS-FTP, rightclick the file and select Rename. Change it to .htaccess (note the period at the beginning of the name) and save.
Remember that you had to check with your ISP if you are allowed to use or modify htaccess files. Most ISPs allow you to use htaccess. However, some don't. On those ISPs, it can be rather interesting if you upload an htaccess file. It'll overwrite a hidden file and kill your website.
So after you've uploaded and renamed the htaccess file, use your browser to visit your site. If you can see your website, it's okay.
If nothing shows up, well, you've got to call your ISPs tech support and explain that you uploaded an htaccess file and ask them to restore the site. If they refuse to allow you to use htaccess files, then I suggest that you move your site to another ISP.
So, before you start on any of this, check your ISP's FAQ and see if they permit .htaccess files.

Anyway, you've added the htaccess file and your website still works. Let's return to SSI.

Adding the Files to Your Site

In our last episode, we finished making a set of four pages (index, banner, navbar, and footer.) Use your normal file transfer, go to your website, create a folder named test (or whatever) and move the four pages (index, banner, navbar, and footer) into that test folder.

Open the page with your browser. Go to www.yourwebsite.com/test/index.html (or whatever you named it.)

See? The banner, navbar, and footer appear in the page, as it should be.

Rightclick on the page and select View Source to see the HTML. You'll see that there's no mention of the  tags. Instead, the html code for the banner, navbar, and footer appears in place. The server reads the SSI tag, fetches the appropriate code, inserts it, and deliveres the file to your browser. Visit any page at andreas.com and look at the HTML. For the same reason, you won't see the SSI tags.

Now that it works, you can go back and edit your twelve pages. Remove the blocks of HTML code from each page, insert the SSI code that points to each block, and upload everything to your website.

Advanced SSI

There is less HTML complexity to a web page. Your content pages have only content and a handful of short tags. Without SSI, each page would have large blocks of code for each of the universal elements.
You can easily change an element. If you want to change an item across 500 pages, just change the SSI tag that points to that file. Whenever a user pulls up any of the 500 pages, the new item will appear in its spot.
Less chance of errors. By editing a single file, all pages will have identical elements. Without SSI, you have to edit dozens of pages, and if you make a mistake on one, you'll be lucky to find it.
There is a downside: SSI creates extra work for the server. That's why some ISPs don't allow SSIs. For small sites (with less than 500,000 visitors per months, under a few thousand pages, and a few SSIs per page), this isn't an issue. But a large site with heavy traffic, this becomes significant. However, at that level, use Ajax or other tools to include files.

When you build your site, you come up with a site design that will be consistent across all of your pages. You can use tables for layout, and put SSI tags within tables, in order to inject that content into the table cell.

In the steps above, I went through how to create a small set of pages. We didn't bother about layout. When you start to build your real pages, you'll do this in a different way. Since SSI won't let you see the elements in their proper place until you've uploaded it to your SSI-enabled server, you won't be able to see the layout. So first you build a page without using SSI. Use the elements, use tables, and make your layout. When it's finished, you break up the page into various files, by removing elements, saving them as unique files, and replacing each one with an SSI pointer to those files. So... first create a web page in the non-SSI way, finalize your layout, and then convert it to SSI.

You can also put SSI tags within SSI tags. For example, at my site, I often change the photo at the top of the navbar. For example, on Christmas, there'll be a reindeer. To do this, I create the navbar SSI that holds the navbar. In the navbar file, at the top, I have another SSI tag that points to another page that has the HTML code for the image. On that page, I have a list of ten images. I use a comment tag to comment-out nine images, so that one is active. To change the image, I just move the comment tag.

This means that in a SSI file, you can store several versions of the content, and use comment tags to turn off and on the version that you want. For example, if you're planning an event, you can have the pre-event and post-event content in the same file, on your server. On the day of the event, you can open the file, move the comment tags, and save. The pages are instantly updated.

A quick way: Use WS-FTP, rightclick on the SSI file, and select Edit. This opens the page in Notepad. Make your changes and close the page. Don't save, just close it. WS-FTP will save the new version onto your server. Be careful!. If you don't know what you're doing, this is a great way to wreck your website.

Conclusion

SSI is a great tool for my website (1000+ pages.) I have extra text and notes within my SSI files. I can update the navigation menus across all pages in a few lines. It would be otherwise impossible to add or remove an item across a thousand pages.

SSI is fairly obscure. Few people use it, because it normally requires shtml extensions. But by using an htaccess file, you solve that problem.

If you're managing websites and you convert them to SSI, you're employed for life, because nobody else can figure out what you did, or even how you did it. Go to my website and open the HTML source code. See? There's nothing to see. Not a single line of SSI code. The code doesn't leave a trace. The server processes the SSI and produces plain HTML.

Comments

David asks: (August 2018) I’m redoing my wife's (and my) website, and I'm ditching our old CMS to go back to good old hand-coded HTML, CSS, and server-side includes. From what I read on your page about SSI, you changed the .htaccess so that .html files are parsed as .shtml files. Have you noticed any detrimental impact on server load? All of the warnings I’ve read about parsing .html as .shtml are about 20 years old. Standard sever power is much higher today as compared to when folks were warning webmasters away from processing .html as .shtml like they were back in 1998.

My Reply: David, I stopped using SSI in 2013 or so when I switched to Wordpress. I really liked SSI: it allowed me to modularize my website. I could add/edit/hide/remove blocks of code and text easily across 1,000+ pages.

Yes, there was a bit of lag, but in 2003-2015, that didn't matter much. It impacted only the user experience. My site was simple, so it didn't matter. However, if any large site (for example, Amazon) used SSI, they would be loading a hundred or more modules (e.g., there are +50 trackers on many of the large sites) and that would definitely affect load speed.

But now, there's Google's page-load-speed issue, especially for mobile users. Google is prioritizing fast pages for mobile users. If your page is competing against similar pages and all else is equal, then speed is a factor, but generally, pages aren't equal. I do SEO for a major university; their mobile traffic grows at about 1-2% per month. We expect it'll be 80-90% in a few years. I looked at a prospective client's analytics a few days ago: in January, his incoming traffic was 30% mobile; last week, it was 55% mobile. I told him that he'll have to change his site from desktop-centric to mobile-centric: i.e., short 3-5 line blocks of text and images at 350 pixels wide. That'll be a huge change for his site: he has very long pages of text and very large images.

Large sites are also using Google AMP. I need to look into that to see if it's worthwhile to implement on andreas.com. I don't know if you can combine AMP and SSI.

Another issue: Many users allow Google to use predictive page pre-loading (Chrome loads in the background what it thinks users will do next). This may overcome any SSI delay.

So the answer is: I don't know if the speed of SSI will hurt or not matter. For small personal sites like yours and mine, I doubt it.