Algorithm

Back to Implementation

This page describes the algorithm Remark uses to generate the resulting web-pages. Before reading this page you should be familiar with concepts.

Constructing the document tree

Gathering files and directories

This step gathers a linear list of those files that are located in the input directory or its sub-directories. Files are identified with their location relative to the input directory (called a root name). Only those files are accepted which have an associated document type or are explicitly specified at the invocation of Remark.

After the files have been gathered, their containing directories are gathered. If a directory is gathered, then so is its parent directory (unless the directory is the input directory). This set of directories is useful when one wants to generate a directory view.

Parsing files

Each file in the set of input files is parsed for tags using its own associated tag parser. The purpose of this phase is to find out for a file its parent document, description, and a detailed description.

Resolving explicit links

If a file specifies a parent document, then it is used to construct a part of the document tree. The parent document is allowed to be given as a simple filename only. If the file is not found in the current directory, then parent directories are searched repeatedly until a match is found or one reaches the input directory. If the parent file is not found, a warning is emitted (the filename might be misspelled or the file really missing).
If a documentation file (.txt) does not specify a parent document, a warning is emitted. Other types of documents might still be deduced a parent implicitly.

Resolving implicit links

If a file does not have a parent document at this point, it is attempted to give an implicit parent. This procedure is described in concepts.

Linking orphans

If a file does not have parent document even after implicit linking, it is linked to a special orphan document. This guarantees that each file has a parent document. By generating a web-page that contains all the orphans, the user has a useful list of those files which are not linked to the documentation. This is what the .orphan document type is used for.

Add some virtual documents

Using the list of involved directories, a directory.index document is generated to each sub-directory of the document tree. In addition, an orphan.orphan document is generated to the root directory of the document tree.

Generating output

For each file in the document tree:

  1. Recursively expand the Remark macros in its document template (given by the document type).

  2. Convert the resulting Markdown source to html.

  3. Add html boilerplate code around the generated html (such as defining the .css files to use).

  4. Create the directories leading to the output file if they don't exist.

  5. Save the generated html to the output file (with the input extension replaced with the output extension).

Copying some files

Those files which have no associated document type, but are located at the documented directories, are simply copied to the corresponding output directories. However, if a particular file already exists at the output directory, it is not copied over.

At the end, three files are copied (if they don't exist) to the remark_files directory of the output directory. These are:

remark.css
To control the styling of the generated web-pages in general.
pygments.css
To control the styling of the source-code bits.
ASCIIMathMLwFallback.js
To convert AsciiMath to MathML on the fly.