For most pages, will be plain unadorned reStructuredText pages with a .rst or .txt extension. You may optionally add a number of YAML fields and values as a header to these rST pages as metadata. csc passes the metadata from the header section to the template directly. The following meta values are special and read from the files:
- template the name and path of the template file that csc will use to render the page.
- output the name of the file that csc will write the output file. If not specified csc will use the current file name and path (with the .html extension.) This option is typically not specified.
- builddir the path of the output file. This option is typically not specified.
Consider the following example of an aggregated page:
type: directory_archive preamble: this is the preamble postamble: this is the post-amble. lol. title: an aggregated page, created directory: test/
This will generate a file named directory.html, that contains a list (i.e. archive) of all the files in the test/ directory. Specify the directory in the test/ relative to the top level of the source directory, and the corresponding links will be similarly relative to the top level of the output directory.
You may also specify directory_include which will create a restructured text page with include:: directives. When rendered, the resulting page will have the content of all files in the directory.
title: 'this is a title' type: archive archive: - input.rst - shell-line-eding.rst preamble: "this is a bit of text and I think that its important to have text before the list." postamble: "this is text and it goes after the end of things."
In this example, rather than including all pages in a directory, you can specify a list of files and generate either an a list of pages as above (i.e. archive) or an included page (i.e. include.)
type: generate title: this is a generated page preamble: this is the preamble postamble: this is the post-amble. lol. input: test/ filter: tag: 'people' sort: 1 limit: 5 final_type: archive
The generate page type creates an aggregated page with some sort of constraint. You may understand the process for generating a page using a very simple pipeline: pass the name of a directory in the input value the contents of tat the pipeline considers. The filter is a simple field/value pair that all documents must satisfy. The sort value determines if csa includes source files by ordered in ascending (-1) or descending (1) order. Finally, the limit defines how many aggregated items csa includes.
Generated pages may be either listings (i.e. archive) or composite pages (i.e. include.)