There are a few places in PieCrust where you need to specify a reference to a page — like for instance when defining taxonomies and specifying a custom index page.
Page references are written using the following format:
source_name:path/to/page.ext
This means:
source_name: The source in which to find the page.
path/to/page: A source path to the page. This is usually just a
file-system relative path, starting from the file-system endpoint of the
source, but some sources may have slightly different ways to specify a
relative path. Refer to the source’s documentation.
.ext: The extension to use. If you want to the user to have some freedom in
the matter — like for example letting the user use either a .md or
.textile extension to use either Markdown or Textile syntax — then you can
use .%ext%. This will match any extension registered in the
site/auto_formats settings (see the formatters documentation).
It’s possible to define a reference that will match multiple possible pages —
in this case, it would resolve to the first found page. Just write additional
page references, using ; as a separator.
For instance:
foo:something/whatever.md;bar:someting.md
…would match something/whatever.md in source foo if it exists, otherwise
it would match something.md in source bar if it exists. Otherwise, the page
isn’t found.
This is especially useful for falling back to a page defined in a theme.