Content management

Content is stored as regular files and organized with directories and naming.

Content directory

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).

Tip

The front page is content/index.

Warning

All directories must contain an index page file.

Naming

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.

Warning

On generation a sitemap.xml will be created, unless disabled in site configuration. A page can therefor not be called content/sitemap.xml.

Important

Name syntax: [<sort order>_]<title>[.<extension>]

Title

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(.).

Sort order

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.

Tip

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.

Extension

An extension is optional and is left as is. Directory index files can have extensions.

URL

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.

Name examples
Name Title URL
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

Headers

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.

Page headers
Name Default Description
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

Header profiles

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.

reStructuredText

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.

Tip

robots.txt or .htaccess are files that should be configured with generate html: false header.

Executable files

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)"