RubyFrontier Documentation

The Autoglossary

The autoglossary is the mechanism by which pages in your Web site can refer easily to one another via links. The key to this mechanism is a file, #autoglossary.yaml, which RubyFrontier maintains at the top level of your source folder.

Links are not hard to make, and you could easily construct a relative link from one page to another manually. So what’s the point of the autoglossary mechanism? Well:

Executive Summary of the Autoglossary Mechanism

Every time you render (publish) a page object, RubyFrontier automatically adds information about that page object into the #autoglossary.yaml file. It keys that information twice: under the simple name of the page object (the filename without the extension) and under the title of the page object if there is one (probably, the value of the page object’s #title scalar directive).

Then, later, when you want to form a link from one page in your site to another page in your site, you create an <a> tag just as you would expect, but you do not hard-code a relative URL into its href attribute. Instead, for the <a> tag’s href attribute, you use the target page’s key in the #autoglossary.yaml file. As I just said, that can be either the simple name of the target source page file or the title of the target page. RubyFrontier then looks up that key in the #autoglossary.yaml file, calculates the relative URL, and substitutes it for your href value, as the page is rendered.

How Stuff Gets Into the Autoglossary

The autoglossary is maintained for you. You should never have to tweak it or edit it in any way. There are two ways in which the autoglossary gets built.

The second way of getting info into the autoglossary is more important than you might think. For one thing, without it, the autoglossary can become “stale” (storing info about pages that no longer exist or whose title or filename you’ve changed). Also, it is the only way that information about non-renderables can get into the autoglossary. A non-renderable is, for example, a .pdf file included in your site. It’s part of your site, and when you say Publish Folder or Publish Site, non-renderables are simply copied from the source folder to the Web site folder. Clearly you might want to be able to link to a non-renderable (without a link, users of your site may never find the file). You can do so, via the autoglossary mechanism.

How Stuff Gets Out of the Autoglossary

To get RubyFrontier to consult the autoglossary for you, in a renderable page object, form a link where the href attribute is the title or simple name of a page object file:

    <a href="otherpage">Click me!</a>

In that example, RubyFrontier looks up otherpage in the autoglossary and, if it finds it, it works out the relative URL from the page being rendered to that other page, and substitutes the resulting relative URL as the value of the href attribute.

How you form the link is up to you. You can form it manually, or during macro processing, or through Markdown syntax:

    [Click me!](otherpage)

The only requirement is that it be transformed into a normal HTML link before the moment during the rendering process when RubyFrontier deals with autoglossary links.

If your link contains any other attributes, RubyFrontier will leave them alone. But it is essential that the href attribute be the first attribute. So, for example, this will work:

    <a href="otherpage" class="someclass">Click me!</a>

In that example, otherpage will be looked up in the autoglossary and the proper relative URL substituted for it in the href attribute, and the class attribute will remain present as part of the <a> tag.

If your link includes an anchor, the anchor will remain. So, for example, this will work:

    <a href="otherpage#someanchor">Click me!</a>

In that example, otherpage will be looked up in the autoglossary and the proper relative URL substituted for it in the href attribute, with #someanchor appended to it.

How does RubyFrontier know whether to look up an href value in the autoglossary? The answer is that if the href value contains a dot (.), or a colon-slash-slash (://), or starts with a pound-sign (#), RubyFrontier assumes that this is an absolute URL and leaves it alone; it won’t look up that href value in the autoglossary. But in the first two cases, you can signal to RubyFrontier that it should look up the href value in the autoglossary, by “escaping” the dot or the colon-slash-slash with a preceding backslash.

What If Autoglossary Lookup Fails?

If RubyFrontier looks up an href value in the autoglossary and doesn’t find it, it then looks up the value in the normal glossary.

If lookup in both the autoglossary and the normal glossary fails, RubyFrontier assumes you’ve made an error. This error is not fatal; rendering of the page object continues. But an error message is issued, and RubyFrontier substitutes, as the value of the href attribute, "errorRefGlossaryFailedHere". So you can find failed autoglossary substitutions in a generated Web page by searching for "errorRefGlossaryFailedHere" in the Web page’s HTML.

Links to Other RubyFrontier Sites

RubyFrontier can also use the autoglossary mechanism to generate URLs to other RubyFrontier-based sites that you maintain. For example, I maintain pages at and at What if a page in the TidBITS site wants to link to a page in the Apeth site? Of course I can do this with an absolute URL; but this means that I must get the URL right, plus if I move a page within the Apeth site I have to remember to change any links to it from within the TidBITS site. Instead, I let RubyFrontier’s autoglossary mechanism help me.

For this to work, two things are necessary:

For example, my Apeth source folder’s #ftpsite.yaml file contains this line:


The result is that when the Apeth source folder’s autoglossary entries are made in its #autoglossary.yaml file, they include a :url key whose value is the absolute URL of the individual Web page. Then, when I’m generating a page in the TidBITS site, if the page wants to link to a page of the Apeth site, RubyFrontier can look directly in the #autoglossary.yaml file for the Apeth site, and fetch the absolute URL for the page that I’m linking to.

Clearly, then, the relative location of the Apeth site from the TidBITS site must be known, so that RubyFrontier can find the #autoglossary.yaml file for the Apeth site while it’s building a page in the TidBITS site.

Here’s how this part of the mechanism works. An href value needs to be of the form sitename^pagename — the name of the site, followed by a caret, followed by the simple name of the page (the key that will be consulted in the other site’s autoglossary). The sitename can be anything, because it isn’t a real name; it is just a key in your glossary. (For example, it might be in a #glossary.yaml file.) The value for that key must the relative filepath from the source folder of this site to the source folder of the other site.

For example, here is how my source folders are arranged together in the Finder (the one called “site” is the TidBITS site):

Figure 1: Three source folders (and the TextMate project files that maintain them), as shown in the Finder on my computer.

So in the TidBITS site I have a glossary entry like this:

    apeth: ../../apethWebSite/apeth/

In this way, an href attribute value "apeth^appleHelpTalk" in the TidBITS site is translated into the absolute URL of the file appleHelpTalk.mp3 within the Apeth Web site.

NOTE for Frontier users: The glossary mechanism in Frontier suffered from some problems: it was overloaded, and glossary resolution took place too late in the page rendering process for many purposes. In RubyFrontier, therefore, the Frontier glossary mechanism is split into three pieces:

Next: Glossary Expansion

This documentation prepared by Matt Neuburg, phd = matt at tidbits dot com (, using RubyFrontier.
Download RubyFrontier from GitHub.