-
Notifications
You must be signed in to change notification settings - Fork 133
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
.
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.
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.
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)
An example of how pages are displayed within the documentation FORD produces is given below.
Home | About | Writing Documentation | Running Ford | Copyright © 2015 Chris MacMackin