This page introduces the main concepts and terminology that are used in Remark.
Remark divides the files in the input directory into three classes:
Files which have an associated document type, called documentation files.
Additional files which were specified when invoking Remark from the console, and which are not documentation files, called auxiliary files.
The remaining files.
The documentation files and the auxiliary files are together called documents. When Remark works with the files:
The files in the class 3 are ignored.
The files in the class 2 are copied as they are into the output directory, unless they already exist there.
The files in the class 1 are treated differently based on the associated document type.
A documentation file is associated to a document type by its filename extension. A document type encapsulates the following processes:
Parsing of tags from a document given the name of the input file.
Computation of the document template given the the name of the input file.
Computation of the name of the output file given the name of the input file.
Deciding if AsciiMath is interpreted or not in the generated page.
A document template is a piece of text in Remark syntax which, when expanded, generates the output file in Markdown syntax (to which html can be embedded). This template is generated by the document type of a document. Most often this includes reading the contents of the file and representing it in some other, perhaps more convenient form. For example, if the file were a source code file written in some programming language, the document template could apply highlighting to the code to make it easier to read.
Every file under Remark is associated with a unique parent document file. This parent-child relation induces a tree where the documents are nodes and the edges denote a parent-child relation. This tree is called the document tree and is used to generate various useful information automatically. The root of this tree is called the orphan node. If a document does not get assigned a parent, it will be assigned to a child of the orphan node. This node is useful as a way to check if one has remembered to link all files into the documentation.
Tags embed information relevant to Remark into the documents. The way the tags are read from a document is dependent on its associated document type and, more specifically, is encapsulated into tag parsers. A tag parser is a Python class which implements a procedure to extract tags from specific types of documents. The tag parsers can extract whatever information they want, however, the following three bits of information are especially important for Remark:
The name of the parent document file.
A rough description of the file (one line).
A more detailed description of the file (one line).
These information are important because they allow to deduce the form of the document tree (via parent documents), and to automatically name links (via descriptions).