Writing Pages

If a page_dir is specified in the metadata of your project file, then FORD will produce a set of pages from the contents of this directory. These pages will not be associated with any source code. The "homepage" for this documentation will be a file by the name of index.md in page_dir.

Writing Pages

Pages are written in Markdown and their files must have the extension .md (otherwise they will not be processed). All of the same Markdown extensions will be available here as were when processing the project description and any documentation. Files may have the following metadata:

• title: the name of the page (required)
• author: the author of the page (optional)
• date: the date the page was written (optional)

Links to the documentation can be used in the same was as from within the documentation.

Hierarchy

It is possible to have subpages, nested to an arbitrary level. This is achieved using the directory hierarchy within page_dir. Each directory represents a page and all of its subpages. The page which a directory represents must have the file-name index.md, or else that directory will be skipped by FORD. Any other Markdown files within the directory correspond to subsidiary pages in the hierarchy. And subdirectories correspond to subsidiary pages which themselves have subsidiary pages.

For example, the following directory structure (with page titles given in parentheses)

page_dir
├── index.md (README)
├── changelog.md (ChangeLog)
├── equations.md (Fluid Equations)
├── examples
|   ├── index.md (Example Simulations)
|   ├── shock.md (1D shock tube)
|   └── collapse.md (Collapsing gas cloud)
└── todo.md (ToDo)

would produce the following page hierarchy

README
├── ChangeLog
├── Fluid Equations
├── Example Simulations
|   ├── Collapsing gas cloud
|   └── 1D shock tube
└── ToDo

The directory structure will be reproduced within the output documentation. The HTML files will have the same names as the original Markdown files, except that the extension is now .html. Because the directory structure is preserved, if the user wishes to provide links between pages then relative links can be used as though the links were being made between the Markdown files (remembering to make the extension html rather than md). Note that all non-Markdown files will be copied into the output directory hierarchy, so relative links to them (e.g. links to images) can also be relative. Within the documentation, pages will be listed in the order of their file names sorted alphabetically.

Example

An example of how pages are displayed within the documentation FORD produces is given below.