Content is stored as regular files and organized with directories and naming.
Pagegen pages are just plain text files containing page options and content organized by directory hierarchy. Each directory is treated as a page containing child pages. For directories the page content is stored in a mandatory index file within each directory. The index file is identical, in both syntax and structure, to regular page files.
Pages (a file or both a directory and file) contain headers(options/settings, also known as front matter) and reStructuredText markup. All page content is located in the content directory (<pagegen directory>/content).
The front page is content/index.
All directories must contain an index page file.
The name of the file, or directory, are used to determine the final page attributes title, URL and optionally menu sort order. The name of pages, both files and directories & index file, are treated the alike, except for the extension. The page path name is used to create the URL to the page.
On generation a sitemap.xml will be created, unless disabled in site configuration. A page can therefor not be called content/sitemap.xml.
Name syntax: [<sort order>_]<title>[.<extension>]
The page title will become the file or directory name without the sort order or extension (unless overridden using Title header, see below). The title can contain any legal file name character, except a period(.).
Pages are sorted in the menu by listing them alphabetically, to override the default sort files and directories can be prefixed by integers followed by an underscore. The sort prefix will be striped from the title and URL.
A good practice is to use increments of 10 when setting the sort prefix (010_, 020_, 030_ etc.). This means an item can be added in the sequence with for instance 011_ without having to rename all items.
An extension is optional and is left as is. Directory index files can have extensions.
The page URL will be the path from the content directory to the file, converted to lower case. Where sort prefix is removed and all characters that are not a-z, 0-9, dash(-), underscore(_) or period(.) are replaced with dash(-), file extensions are kept, if they are present.
|content/Fruit juice||Fruit juice||/fruit-juice|
|content/fruit juice+ice||Fruit juice+ice||/fruit-juice-ice|
|content/0001_Fruit juice||Fruit juice||/fruit-juice|
|content/0001_Fruit juice.html||Fruit juice||/fruit-juice.html|
|content/002_Fruit juice/index.html||Fruit juice||/fruit-juice/|
Page file structure
Content for each page consists of an optional header containing any settings for the page followed by a blank line and reStructuredText markup.
[<header name>: <header value>] [...] The rest is content marked up using reStructuredText
All headers are optional. They must start on the first line and content start is signaled by a blank line after the headers. Headers are often referred to as front matter by static site generation engines.
|category||None||Page category, if exist then /category/<category> pages generated|
|description||None||Html meta tag description|
|generate html||True||Enable/disable parsing of page content|
|header profile||None||If specified default headers will be read from header_profiles/<value>|
|menu exclude||False||Remove page (and child pages) from menu/crumb trail|
|menu title||None||If set use for title in menu/crumb trail|
|preserve file name||False||If True file name will be kept as-is in final url|
|publish||Date of generation||Format YYYY-MM-DD, only generate pages (and sub pages) if today or past|
|rss include||False||If set page is included in RSS feed (assuming site include_rss)|
|search index exclude||False||Exclude page from search index|
|sitemap exclude||False||Remove page from sitemap|
|Sitemap changefreq||None||Values: always, hourly, daily, weekly, monthly, yearly or never|
|Sitemap lastmod||None||Format YYYY-MM-DD|
|Sitemap priority||None||Valuse between 0.0 and 1.0|
|tags||None||Comma separated list of tags, if exist then /tag/<tag> pages generated|
|template||page.tpl||Template file from /templates|
|title||None||If set overrides page title|
Sometimes similar types of pages, e.g. system pages, blog posts or regular article pages, will have the same headers set. Header profiles allows for headers to be defined in a profile, and that profile applied to the pages that reference it in the header profile header.
Header profiles have same syntax as headers and are located in the header_profiles directory.
Headers specified in the page content will override the headers from the profile.
Pages are marked up using reStructuredText.
Some files that comprise a web site may just be regular text files. These files can be setup by using the page header generate html: false, in which case Pagegen will dump file contents as-is, without running it through reStructuredText parser.
robots.txt or .htaccess are files that should be configured with generate html: false header.
Content files may be executables. If a file is executable its content from stdout will be used instead of actual file content. The output form the executable is treated identically to a regular content file, so it may specify headers and non-header content will be parsed as reStructuredText.
Example shell script
#!/bin/bash #Print any desired headers, e.g. echo "Title: This will be the page title" echo "" # Start content echo "$(hostname)"