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)
• ordered_subpage: a list of sub-pages to be linked in order in the table of contents (optional)
• copy_subdir: a list of subdirectories to copy verbatim into generated documentation (optional)

For ordered_subpage and copy_subdir which take a list of arguments, you need to repeat the keyword for each item like so:

ordered_subpage: subpage3
ordered_subpage: subpage1

Links to the source documentation can be used in the same way 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. If you want to refer to a page from the documentation in source files you can make use of the |page| alias to refer to the page_dir of the project (prefix the relative links as described above with |page|.

Within the documentation, pages will be listed in the order of their file names sorted alphabetically. If you want to have sub-pages included in a certain order, you can specify them with ordered_subpage:

title: title of the page
ordered_subpage: subpage3
ordered_subpage: subpage1

The subpages can be another markdown file or a folder. If it is a folder it has to contain again an index.md file where you can order the sub-sub-pages adding them using ordered_subpages in a similar way.

If some file is not added as ordered_subpage it will be added to the documentation at the end of the corresponding level. If no file is in the list, the standard ordering is used.

Copying directories: copy_subdir

This option allows the user to specify subdirectories that are to be copied verbatim into the generated documentation directory.

This setting can also be set in the individual index.md within the page_dir hierarchy. The option allows a convenient collection of supportive files within the page_dir hierarchy, for example to provide images.

Example: project configured with (copy_subdir: media) in the main.md.

Assume the following page_dir structure:

page_dir/
    |- index.md (copy_subdir: images)
                (copy_subdir: plots)
    |- media/
    |- plots/
    |- images/
    |- subtutorial_01/
        |- index.md (copy_subdir: )
        |- media/
    |- subtutorial_02/
        |- index.md (<no option set in file>)
        |- media/

This should produce the a documentation directory as follows:

page/
    |- index.html
    |- plots/
    |- images/
    (media subdirectory not copied, as overwritten in local index.md)
    |- subtutorial_01/
        |- index.html
       (media subdirectory not copied, as overwritten in local index.md)
    |- subtutorial_02/
        |- index.html
        |- media/ (copied due to project settings)

Example

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