Mercurial > piecrust2

annotate docs/docs/04_content-model/04_page-references.md @ 1018:3c6e6e7b9639

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bake: Fix totally broken page baking caused by previous commit.
author Ludovic Chabant <ludovic@chabant.com>
date Wed, 29 Nov 2017 21:35:49 -0800
parents a694b78db0b1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
308
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Page References
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 ---
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5 There are a few places in PieCrust where you need to specify a reference to a
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 page -- like for instance when defining taxonomies and specifying a custom index
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7 page.
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 Page references are written using the following format:
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11 source_name:path/to/page.ext
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 This means:
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15 * `source_name`: The source in which to find the page.
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17 * `path/to/page`: A _source path_ to the page. This is usually just a
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 file-system relative path, starting from the file-system endpoint of the
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19 source, but some sources may have slightly different ways to specify a
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20 relative path. Refer to the source's documentation.
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 * `.ext`: The extension to use. If you want to the user to have some freedom in
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23 the matter -- like for example letting the user use either a `.md` or
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24 `.textile` extension to use either Markdown or Textile syntax -- then you can
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25 use `.%ext%`. This will match any extension registered in the
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26 `site/auto_formats` settings (see the [formatters documentation][fmt]).
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29 ### Multiple matches
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31 It's possible to define a reference that will match multiple possible pages --
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32 in this case, it would resolve to the first found page. Just write additional
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 page references, using `;` as a separator.
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35 For instance:
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 foo:something/whatever.md;bar:someting.md
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 ...would match `something/whatever.md` in source `foo` if it exists, otherwise
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 it would match `something.md` in source `bar` if it exists. Otherwise, the page
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41 isn't found.
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 This is especially useful for falling back to a page defined in a theme.
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45 [fmt]: {{docurl('content/formatters')}}
a694b78db0b1 docs: A whole bunch of drafts for content model and reference pages.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46