This tag defines a Sage volume, the top level in the Sage Hierarchy. The volume consists of all content between the [volume] tag and the matching [end] tag.

The syntax for the [volume] tag is as follows:

[volume <title> aka <alias1> aka <alias2> ...] [//] volume contents: [topic] and [article] tags [end]

Volumes cannot nest: you must end one volume before starting another.

Aliases are often optional, but serve three purposes…

• You can link to an entity (volume, topic, article, or section) by its full title, or by any of its aliases. Typically, aliases provide a shorter way to link to an entity. Additionally, when the Sage web app generates a URL linking to an entity, the URL will be based on the entity's first alias (or the full title, if there are no aliases). This keeps the browser's URL bar cleaner, makes for nicer bookmarks, and allows readers to make and share URLs that are easier to work with.
• If you want to change the title of an entity, but there are already links to the entity's title "in the wild", you can change the title, but leave the old title behind as an alias. This way, existing links will continue to function. After fixing all such links, you can remove the unused alias.
• Aliases establish unique names to the entities that share a namespace, allowing duplicate titles (though never within the same immediate parent). Note: volumes may not have duplicates titles, regardless of aliases. This is because, in effect, all volumes share the same parent: the invisible library that contains all volumes.

As mentioned here, Sage uses an entity's first alias when linking to the entity (or its title if there are no aliases). However, it is sometimes preferable to use the title, even when there are aliases. To accomplish this, use the PrimaryLink attribute, which immediately follows the title…

[article Objects PrimaryLink aka Obj1 aka Obj2]

Above, the article may be referenced in links via any of these names: Objects, Obj, and Obj2. However, when Sage generates a link to this article, it will use Objects. Without the PrimaryLink attribute, Sage would generate links using the first alias, Obj1.

There are several scenarios where PrimaryLink may be useful…

• If all of the aliases are outdated terms, you probably want Sage to avoid using those aliases, in favor of the title itself.
• Even if one or more of the aliases are still current, the title itself may be the preferred option.
• Most importantly, for sections and articles, if multiple entities in the same namespace have the same title, Sage requires each to have an alias, and at that point, the title isn't usable in links. With PrimaryLink, you can identify one of the entities as the one that the title should link to.

Here is an example of the final point in the above list…

[article Objects PrimaryLink] [//] [end] [topic Functions] [article Math aka MathFunctions] [//] [end] [article Objects aka ObjectFunctions] [//] [end] [end]

Above, there are three articles: one at the top level, and two under the Functions topic. The first article is linkable via Objects, thanks to the PrimaryLink attribute. The last article is linkable only via ObjectFunctions. Without PrimaryLink, the link Objects would not be valid (and the first article would need an alias). Overall, this is the main purpose of PrimaryLink.

This tag defines a Sage topic, a hierarchical organization within a volume. Topics may include articles and/or other topics. The topic consists of all content between the [topic] tag and the matching [end] tag.

The syntax for the [topic] tag is as follows:

[topic <title> aka <alias1> aka <alias2> ...] [//] topic contents: [topic] and [article] tags [end]

For more information on the title and alias, see Titles and Aliases.

Topics may only appear within a volume (or nested in another topic).

This tag defines a Sage article, a single web page of content. The article consists of all content between the [article] tag and the matching [end] tag.

The syntax for the [article] tag is as follows:

[article <title> aka <alias1> aka <alias2> ...] [//] article contents: markup text, organized by [section] tags [end]

For more information on the title and alias, see Titles and Aliases.

Articles may only appear within a volume or a topic.

Sage markup (text, images, etc.) may only appear in an article, not directly in a volume or topic.

This tag defines a Sage section, a hierarchical heading within an article. The section consists of all content between the [section] tag and the matching [end] tag.

The syntax for the [section] tag is as follows:

[section <title> aka <alias1> aka <alias2> ...] [//] section contents: markup text, including nested sections [end]

For more information on the title and alias, see Titles and Aliases.

Sections may only appear within an article, and my nest up to six levels deep.

If you want to use Sage markup for the title, use a [title] tag (which must appear immediately after the [section] tag, except for whitespace). For example…

[section ToyStory][title]To [&infin] and ~Beyond~[end] [//] section contents: markup text, including nested sections [end]

The above example creates a section heading that includes the infinity symbol, and an underlined word:

Also, note that the alias(es) are supplied as the body of the [section] tag (and at least one is required). Use "aka" to specify additional aliases:

[section ToyStory aka TS][title]To [&infin] and ~Beyond~[end] [//] section contents: markup text, including nested sections [end]

The above section has two aliases: "ToyStory" and "TS".

This tag defines a Sage "here tag", a location in an article to which links may be defined. This tag has no corresponding [end] tag.

The syntax for the [here] tag is as follows:

[here <alias1> aka <alias2> aka <alias3>...]

For more information on the title and alias, see Titles and Aliases.

Here tags may only appear within an article.