Traffic Server uses the Apache CMS for documentation. Beyond that the project has adopted several other conventions in order to make documentation development easier and more consistent.

Directory Structure

The documentation is intended to be translated to multiple languages. For this reason all content file names consist of three parts, separated by dots.

stem.lang.mdtext

Currently only Markdown format is supported, which is indicated by the 'mdtext' suffix. Files with the same stem are considered equivalent. Each directory should contain either exactly one stem, in which case it is a leaf directory, or multiple stems in which case it must contain at least two specific files

  • index.en.mdtext
  • order.txt

index.en.mdtext is the index file for the directory and is considered the text for the directory itself. All other stems and directories are treated as children. The order.txt file must contain a white space delimited list of all the stems in the directory. This is determines the ordering of the stems so that navigation links can be generated. Note that other language variants of the index stem can be present, but it is required that there be an English language index.

For a leaf directory, the stem can be any name. It is treated as the text for the directory. No order.txt is needed as there is only one item.

Header variables

The Apache CMS allows each content file to contain header variables which are used by the templates. These must be the first text in the file and are terminated by an empty line. Each variable consists of a name, followed by a colon, a space, and the the value of the variable. As an extension to this, you may use a 'vars.txt' file. When a content file is processed, any vars.txt files from the root document directory down to the content file directory are processed for variables. These are processed in that order so that a definition in the content file directory overrides a value defined in a vars.txt in a containing directory (this is modeled on .htaccess file rules). A variable definition in the content file itself override the value in any vars.txt.

Variables used by templates

  • Title Page title.
  • Doc Documentation title. This is placed in a smaller font over the page title.
  • AltLangText Fixed text to use for alternate language links. Defaults to "Languages". This should be used for translated pages to translate that text.
  • Navigation Control the navigation links. These are generated by default. This is needed only to override the default, most usefully for root pages. The value must be a white space separated list of links in Markdown format. These are placed in the navigation bar. You can include the generated links with the notation [tag](☆) where tag is one of the default names, "Next", "Back", "Top", "Up" and the "☆" is literal. If the link is inappropriate (e.g., "Back" for the first item) the link is silently discarded. The notation [☆](☆) (two literal "☆") will insert all appropriate generated links that have not been explicitly included (e.g., if a "Next" link is already present, it will not be added).

How to build the docs

Checkout the CMS:

$ svn co https://svn.apache.org/repos/infra/websites/cms/build cms

Checkout the docs:

$ svn co https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms

Build the docs:

$ cd ats-cms
$ ./build.sh

To view the docs, point an HTTP Server to ats-cms-doroot/content.

  • No labels