Organizing Your Site with KeenSpace Tags

To begin understanding how Autokeen works, read Understanding Autokeen. You will also want to read Atrus's Taglossary to get an overview of KeenSpace tags.

This tutorial will elaborate on that introduction, and offer tips on organizing your site using Keenspace tags. Much of this information I discovered by trial and error. Thanks also to the Keenspace members who offered invaluable help and information in the Help Center, especially sixguys, Phalanx, and of course, Kisai.

This tutorial will assume you have already read the Cadet's Handbook and Ensign's Handbook on Gear, and are familiar with how your Keenspace account works, the Autokeen script, and how to run a manual update. It also assumes you have some basic familiarity with HTML.

File Structure on Keenspace

As you should know by now if you have read the links above, your Keenspace account contains two folders: public_html and workspace. Under normal circumstances, you never want to upload directly to the public_html folder or even touch it (although to explain how Autokeen works, we will be looking inside it during this tutorial). Instead, everything should be uploaded into workspace. You then run a manual update to cause Autokeen to move files from workspace to public_html. Understanding exactly how this is done, especially in conjunction with Keenspace tags, is essential to keeping a site organized, especially if you want to add new pages, subfolders, static content imported into dynamic pages, and so on.

In your workspace folder, you have two HTML files and three subdirectories.

The two HTML files are indextemplate.html and dailytemplate.html. The three subfolders are comics, images, and webpages.

When Autokeen runs, it does the following:

Scans through all files in workspace and its subfolders, and interpolates any Keenspace tags it finds.
Copies all files in workspace/images to public_html/images.
Moves (not copies) all files in workspace/comics to public_html/comics if they are in date format and the date is equal to or less than the current date. All files whose dates are in the future remain in the workspace/comics folder. (This part is also done when Autokeen runs automatically, at the times you have specified in your Admin settings).
Generates archive pages (in the public_html/d and public_html/w folders) for each of your comics, using the dailytemplate.html in your workspace folder as a template, processing all its Keenspace tags, and inserting correct links to the given comic and other files of the given day.
Finds all files in workspace/webpages, moves them to public_html, and processes their Keenspace tags.
Builds an index.html page by copying indextemplate.html (after processing Keenspace tags), and moves it to public_html. This becomes your site's "front page" (what everyone will see when they type just the base URL to your keenspace.com address).

Relative and Absolute Paths

It seems fairly complicated, but it is all pretty straightforward once you get used to how things are organized after Autokeen processing. Everything in your workspace/webpages folder goes into the "root" directory of your public site (what is in public_html), and all links are relative from there. What can make it tricky is when you want to link to other files (such as images) or folders in your directory.

For example, suppose you have a file sample_image.jpg in your workspace/images folder. You want to link to it from a page gallery.html which is in workspace/webpages.

If you are familiar with relative paths, you know that if this directory structure was preserved on your public site, the link tag would be:

<img src="../images/sample_image.jpg">

But this won't work! If you have been paying attention, you already know why. When Autokeen runs, it will copy gallery.html into public_html, and sample_image.jpg into public_html/images. So for a relative path to work after Autokeen processing, it must be:

<img src="images/sample_image.jpg">

Now what if you put gallery.html into a subfolder called extras? Then before Autokeen processing its full path will be workspace/webpages/extras/gallery.html, and after Autokeen processing it will be found at public_html/extras/gallery.html. Now your link to the image would have to be:

<img src="../images/sample_image.jpg">

This can become even more of a hassle if you reorganize your site. Now you have to change all of your links.

There are times when relative paths are preferable, but on Keenspace, you will often find an absolute path (one that starts with '/') is preferable, as long as you know that what you are linking to will always be in the same location relative to your root directory. For example, if you use the following link:

<img src="/images/sample_image.jpg">

(note the '/' at the beginning!) it will work no matter where in your public_html file hierarchy you put it. It will always look for sample_image.jpg in an images folder directly below your root directory.

This is also a good technique to use with Cascading Style Sheets. If you want to use a CSS document to set a consistent look and feel across your site, you need to link to that sheet from each page. If your stylesheet is mystyle.css in your root directory, then using relative links, each page in your top-level directory would link to it as follows:

<LINK REL="stylesheet" TYPE="text/css" TITLE="My Style" HREF="mystyle.css">

But any pages in a subfolder of your root directoy would have to link to it using this reference:

<LINK REL="stylesheet" TYPE="text/css" TITLE="My Style" HREF="../mystyle.css">

And if you move them to a different level of the hierarchy, that link will break. Instead, use an absolute path:

<LINK REL="stylesheet" TYPE="text/css" TITLE="My Style" HREF="/mystyle.css">

Now it won't matter where in your hierarchy the page is located, it will always find the stylesheet (as long as you don't move that!).

Keenspace Tags

Now that you have your hierarchy organized, you need to make sure your tags work correctly. Keenspace tags interpolate a block of text or HTML code into the page they are placed in, so when that page is copied from workspace to public_html, the page, what gets copied to the public page contains text or HTML where the tag is located in the workspace page.

In most cases, this is straightforward enough, but it gets tricker when you use the ***include*** tag. This allows you to create a separate file (for example, a sidebar, a footer, or a "News" blurb), with text that you want to update on occasion and have that update be reflected on every page on your site. Manually copying the new text onto every page is time-consuming, tedious, and error-prone. Instead, you can have each page ***include*** a file containing that text, and then merely change that file. After running a manual update, every page with an ***include*** tag for that file will have the updated text.

Or will it?

You see, your included files can also have Keenspace tags in them. And you can use ***include*** in an included file (i.e., use nested file inclusions).

This will work! But, it requires multiple updates!

The easiest way to illustrate this is with an example.

name.html
*author* <p> *include name1.txt*

name1.txt
*include name2.txt* <p> *author*

name2.txt
***include name3.txt***
<p>
***author***

name3.txt
<p>
***author***

We would expect, eventually, to see the author's name repeated four times on name.html But this will take four consecutive updates!

To discover how this works, looking at the contents of these files after Autokeen runs and they are copied to the public_html folder is informative.

Update 1:

name.html has the author's name in the body of the HTML. Autokeen ran, found the ***author*** tag, processed it, and replaced the tag with the appropriate content. But when it found the ***include name1.txt*** tag, it replaced it with... nothing. Why? Because at the time Autokeen ran, name1.txt didn't yet exist in the public_html folder! Finding references to a non-existent file, Autokeen simply ignored the tag and pasted empty space in its place.

But during this same update, Autokeen did find all the text files, and processed each of their tags. If you look in public_html, you will find that all the name*.txt files contain a single instance of the author's name. As with the top-level HTML pages, those text files with ***include*** tags were processed by Autokeen, which found no such files yet in public_html and so ignored them.

Update 2:

Now there are two author's names displayed.

If you look in the text files, you will see that name1.txt and name2.txt each have two instances of the author's name.

Autokeen ran, once again using the files in workspace/webpages to process. This time, it found all the files being referred to in ***include*** tags in public_html, and inserted their contents. But it inserted their contents before processing those files.

In other words, if Autokeen started with name3.txt, processed it, moved it to public_html, then processed and moved name2.txt, and so on up to name.html, then all four instance of the author's name would appear after the first update. But Autokeen only processes one file at a time, and it uses the contents of the public_html directory at the time of processing.

Update 3:

Now three names appear. You should be able to follow the logic... once again, Autokeen processed the files one at a time, inserting the contents of those files already in the public_html directory each time it encountered an ***include*** tag.

Update 4:

And at last, all files have been fully interpolated, and with the last pass, name1.html had its own ***author*** tag processed by Autokeen, then the ***include name1.txt*** found a name1.txt file in public_html which already contained three author's names, and included those in name.html.

Summary

You can probably think of many ways this could be useful: linking alternate images to your archive pages, for example, or including a sidebar which itself may include text from several different sources.

However, nested includes can be problematic, and if you have to guess at how many updates it will take for everything to be processed correctly, you should probably consider a reorganization. I can't think of an obvious reason to do more than one level of nesting.

Also keep in mind that once Autokeen has processed these files, the actual HTML content of the page is fixed. If you change a file that is interpolated by an ***include*** tag, the changes will not be reflected until you do another update, and in the case of nested includes, you will have to do multiple updates again, as describe above.