{{ page.title }}
-{{ page.date_formatted }}
-{{ page.description }}
-%base_url%/assets/ for example:
-!\[Image Title\](%base_url%/assets/image.png)
+files, use Pico's `assets` folder. You can then access them in your Markdown
+using the %assets_url% placeholder, for example:
+!\[Image Title\](%assets_url%/assets/image.png)
### Text File Markup
@@ -121,7 +120,7 @@ classes to your theme. For example, you might want to add some CSS classes to
your theme to rule how much of the available space a image should use (e.g.
`img.small { width: 80%; }`). You can then use these CSS classes in your
Markdown files, for example:
-!\[Image Title\](%base_url%/assets/image.png) {.small}
+!\[Image Title\](%assets_url%/image.png) {.small}
There are also certain variables that you can use in your text files:
@@ -129,9 +128,15 @@ There are also certain variables that you can use in your text files:
* %base_url% - The URL to your Pico site; internal links
can be specified using %base_url%?sub/page
* %theme_url% - The URL to the currently used theme
+* %assets_url% - The URL to Pico's `assets` directory
+* %themes_url% - The URL to Pico's `themes` directory;
+ don't confuse this with %theme_url%
+* %plugins_url% - The URL to Pico's `plugins` directory
* %version% - Pico's current version string (e.g. `2.0.0`)
* %meta.*% - Access any meta variable of the current
page, e.g. %meta.author% is replaced with `Joe Bloggs`
+* %config.*% - Access any scalar config variable,
+ e.g. %config.theme% is replaced with `default`
### Blogging
@@ -154,14 +159,12 @@ something like the following:
`index.twig`), it will create a list of all your blog articles. Add the
following Twig snippet to `blog-index.twig` near `{{ content }}`:
```
- {% for page in pages|sort_by("time")|reverse %}
- {% if page.id starts with "blog/" and not page.hidden %}
-
- {% endif %}
+ {% for page in pages("blog")|sort_by("time")|reverse if not page.hidden %}
+
{% endfor %}
```
@@ -179,75 +182,58 @@ details.
### Themes
-You can create themes for your Pico installation in the `themes` folder. Check
-out the default theme for an example. Pico uses [Twig][] for template
-rendering. You can select your theme by setting the `theme` option in
-`config/config.yml` to the name of your theme folder.
+You can create themes for your Pico installation in the `themes` folder. Pico
+uses [Twig][] for template rendering. You can select your theme by setting the
+`theme` option in `config/config.yml` to the name of your theme folder.
+
+[Pico's default theme][PicoTheme] isn't really intended to be used for a
+productive website, it's rather a starting point for creating your own theme.
+If the default theme isn't sufficient for you, and you don't want to create
+your own theme, you can use one of the great themes third-party developers and
+designers created in the past. As with plugins, you can find themes in
+[our Wiki][WikiThemes] and on [our website][OfficialThemes].
All themes must include an `index.twig` file to define the HTML structure of
-the theme. Below are the Twig variables that are available to use in your
-theme. Please note that paths (e.g. `{{ base_dir }}`) and URLs
-(e.g. `{{ base_url }}`) don't have a trailing slash.
+the theme, and a `pico-theme.yml` to set the necessary config parameters. Just
+refer to Pico's default theme as an example. You can use different templates
+for different content files by specifying the `Template` meta header. Simply
+add e.g. `Template: blog` to the YAML header of a content file and Pico will
+use the `blog.twig` template in your theme folder to display the page.
+
+Below are the Twig variables that are available to use in themes. Please note
+that URLs (e.g. `{{ base_url }}`) never include a trailing slash.
* `{{ site_title }}` - Shortcut to the site title (see `config/config.yml`)
* `{{ config }}` - Contains the values you set in `config/config.yml`
(e.g. `{{ config.theme }}` becomes `default`)
-* `{{ base_dir }}` - The path to your Pico root directory
* `{{ base_url }}` - The URL to your Pico site; use Twig's `link` filter to
specify internal links (e.g. `{{ "sub/page"|link }}`),
this guarantees that your link works whether URL rewriting
is enabled or not
-* `{{ theme_dir }}` - The path to the currently active theme
* `{{ theme_url }}` - The URL to the currently active theme
-* `{{ version }}` - Pico's current version string (e.g. `2.0.0`)
+* `{{ assets_url }}` - The URL to Pico's `assets` directory
+* `{{ themes_url }}` - The URL to Pico's `themes` directory; don't confuse this
+ with `{{ theme_url }}`
+* `{{ plugins_url }}` - The URL to Pico's `plugins` directory
+* `{{ version }}` - Pico's current version string (e.g. `%version%`)
* `{{ meta }}` - Contains the meta values of the current page
- * `{{ meta.title }}`
- * `{{ meta.description }}`
- * `{{ meta.author }}`
- * `{{ meta.date }}`
- * `{{ meta.date_formatted }}`
- * `{{ meta.time }}`
- * `{{ meta.robots }}`
+ * `{{ meta.title }}` - The `Title` YAML header
+ * `{{ meta.description }}` - The `Description` YAML header
+ * `{{ meta.author }}` - The `Author` YAML header
+ * `{{ meta.date }}` - The `Date` YAML header
+ * `{{ meta.date_formatted }}` - The formatted date of the page as specified
+ by the `date_format` parameter in your
+ `config/config.yml`
+ * `{{ meta.time }}` - The [Unix timestamp][UnixTimestamp] derived from the
+ `Date` YAML header
+ * `{{ meta.robots }}` - The `Robots` YAML header
* ...
* `{{ content }}` - The content of the current page after it has been processed
through Markdown
-* `{{ pages }}` - A collection of all the content pages in your site
- * `{{ page.id }}` - The relative path to the content file (unique ID)
- * `{{ page.url }}` - The URL to the page
- * `{{ page.title }}` - The title of the page (YAML header)
- * `{{ page.description }}` - The description of the page (YAML header)
- * `{{ page.author }}` - The author of the page (YAML header)
- * `{{ page.time }}` - The [Unix timestamp][UnixTimestamp] derived from
- the `Date` header
- * `{{ page.date }}` - The date of the page (YAML header)
- * `{{ page.date_formatted }}` - The formatted date of the page as specified
- by the `date_format` parameter in your
- `config/config.yml`
- * `{{ page.raw_content }}` - The raw, not yet parsed contents of the page;
- use Twig's `content` filter to get the parsed
- contents of a page by passing its unique ID
- (e.g. `{{ "sub/page"|content }}`)
- * `{{ page.meta }}`- The meta values of the page (see `{{ meta }}` above)
- * `{{ page.previous_page }}` - The data of the respective previous page
- * `{{ page.next_page }}` - The data of the respective next page
- * `{{ page.tree_node }}` - The page's node in Pico's page tree
-* `{{ prev_page }}` - The data of the previous page (relative to `current_page`)
-* `{{ current_page }}` - The data of the current page (see `{{ pages }}` above)
-* `{{ next_page }}` - The data of the next page (relative to `current_page`)
-
-Pages can be used like the following:
-
-
-
-Besides using the `{{ pages }}` list, you can also access pages using Pico's
-page tree. The page tree allows you to iterate through Pico's pages using a tree
-structure, so you can e.g. iterate just a page's direct children. It allows you
-to build recursive menus (like dropdowns) and to filter pages more easily. Just
-head over to Pico's [page tree documentation][FeaturesPageTree] for details.
+* `{{ prev_page }}` - The data of the previous page, relative to `current_page`
+* `{{ current_page }}` - The data of the current page; refer to the "Pages"
+ section below for details
+* `{{ next_page }}` - The data of the next page, relative to `current_page`
To call assets from your theme, use `{{ theme_url }}`. For instance, to include
the CSS file `themes/my_theme/example.css`, add
@@ -255,19 +241,94 @@ the CSS file `themes/my_theme/example.css`, add
to your `index.twig`. This works for arbitrary files in your theme's folder,
including images and JavaScript files.
-Additional to Twigs extensive list of filters, functions and tags, Pico also
-provides some useful additional filters to make theming easier.
+Please note that Twig escapes HTML in all strings before outputting them. So
+for example, if you add `headline: My favorite color` to the
+YAML header of your page and output it using `{{ meta.headline }}`, you'll end
+up seeing `My favorite color` - yes, including the markup! To
+actually get it parsed, you must use `{{ meta.headline|raw }}` (resulting in
+the expected My **favorite** color). Notable exceptions to this
+are Pico's `content` variable (e.g. `{{ content }}`), Pico's `content` filter
+(e.g. `{{ "sub/page"|content }}`), and Pico's `markdown` filter, they all are
+marked as HTML safe.
+
+#### Dealing with pages
+
+There are several ways to access Pico's pages list. You can access the current
+page's data using the `current_page` variable, or use the `prev_page` and/or
+`next_page` variables to access the respective previous/next page in Pico's
+pages list. But more importantly there's the `pages` function. No matter how
+you access a page, it will always consist of the following data:
+
+* `{{ id }}` - The relative path to the content file (unique ID)
+* `{{ url }}` - The URL to the page
+* `{{ title }}` - The title of the page (`Title` YAML header)
+* `{{ description }}` - The description of the page (`Description` YAML header)
+* `{{ author }}` - The author of the page (`Author` YAML header)
+* `{{ date }}` - The date of the page (`Date` YAML header)
+* `{{ date_formatted }}` - The formatted date of the page as specified by the
+ `date_format` parameter in your `config/config.yml`
+* `{{ time }}` - The [Unix timestamp][UnixTimestamp] derived from the page's
+ date
+* `{{ raw_content }}` - The raw, not yet parsed contents of the page; use the
+ filter to get the parsed contents of a page by passing
+ its unique ID (e.g. `{{ "sub/page"|content }}`)
+* `{{ meta }}` - The meta values of the page (see global `{{ meta }}` above)
+* `{{ prev_page }}` - The data of the respective previous page
+* `{{ next_page }}` - The data of the respective next page
+* `{{ tree_node }}` - The page's node in Pico's page tree; check out Pico's
+ [page tree documentation][FeaturesPageTree] for details
+
+Pico's `pages()` function is the best way to access all of your site's pages.
+It uses Pico's page tree to easily traverse a subset of Pico's pages list. It
+allows you to filter pages and to build recursive menus (like dropdowns). By
+default, `pages()` returns a list of all main pages (e.g. `content/page.md` and
+`content/sub/index.md`, but not `content/sub/page.md` or `content/index.md`).
+If you want to return all pages below a specific folder (e.g. `content/blog/`),
+pass the folder name as first parameter to the function (e.g. `pages("blog")`).
+Naturally you can also pass variables to the function. For example, to return a
+list of all child pages of the current page, use `pages(current_page.id)`.
+Check out the following code snippet:
+
+ %base_url%) in
+ arbitrary strings using the `url` filter. This is helpful together with meta
+ variables, e.g. if you add image: %assets_url%/stock.jpg
+ to the YAML header of your page, `{{ meta.image|url }}` will return
+ `%assets_url%/stock.jpg`.
* To get the parsed contents of a page, pass its unique ID to the `content`
filter (e.g. `{{ "sub/page"|content }}`).
-* You can parse any Markdown string using the `markdown` filter (e.g. you can
- use Markdown in the `description` meta variable and later parse it in your
- theme using `{{ meta.description|markdown }}`). You can pass meta data as
- parameter to replace %meta.*% placeholders (e.g.
- `{{ "Written *by %meta.author%*"|markdown(meta) }}` yields "Written by
- *John Doe*").
+* You can parse any Markdown string using the `markdown` filter. For example,
+ you might use Markdown in the `description` meta variable and later parse it
+ in your theme using `{{ meta.description|markdown }}`. You can also pass meta
+ data as parameter to replace %meta.*% placeholders
+ (e.g. `{{ "Written by *%meta.author%*"|markdown(meta) }}` yields "Written by
+ *John Doe*"). However, please note that all contents will be wrapped inside
+ HTML paragraph elements (i.e. `…
`). If you want to parse just a single + line of Markdown markup, pass the `singleLine` param to the `markdown` filter + (e.g. `{{ "This really is a *single* line"|markdown(singleLine=true) }}`). * Arrays can be sorted by one of its keys using the `sort_by` filter (e.g. `{% for page in pages|sort_by([ 'meta', 'nav' ]) %}...{% endfor %}` iterates through all pages, ordered by the `nav` meta header; please note the @@ -285,18 +346,6 @@ provides some useful additional filters to make theming easier. Twig! Simply head over to our [introductory page for accessing HTTP parameters][FeaturesHttpParams] for details. -You can use different templates for different content files by specifying the -`Template` meta header. Simply add e.g. `Template: blog` to the YAML header of -a content file and Pico will use the `blog.twig` template in your theme folder -to display the page. - -Pico's default theme isn't really intended to be used for a productive website, -it's rather a starting point for creating your own theme. If the default theme -isn't sufficient for you, and you don't want to create your own theme, you can -use one of the great themes third-party developers and designers created in the -past. As with plugins, you can find themes in [our Wiki][WikiThemes] and on -[our website][OfficialThemes]. - ### Plugins #### Plugins for users @@ -429,6 +478,7 @@ url.rewrite-if-not-file = ( For more help have a look at the Pico documentation at http://picocms.org/docs. [Pico]: http://picocms.org/ +[PicoTheme]: https://github.com/picocms/pico-theme [SampleContents]: https://github.com/picocms/Pico/tree/master/content-sample [Markdown]: http://daringfireball.net/projects/markdown/syntax [MarkdownExtra]: https://michelf.ca/projects/php-markdown/extra/ @@ -438,6 +488,7 @@ For more help have a look at the Pico documentation at http://picocms.org/docs. [Composer]: https://getcomposer.org/ [FeaturesHttpParams]: http://picocms.org/in-depth/features/http-params/ [FeaturesPageTree]: http://picocms.org/in-depth/features/page-tree/ +[FeaturesPagesFunction]: http://picocms.org/in-depth/features/pages-function/ [WikiThemes]: https://github.com/picocms/Pico/wiki/Pico-Themes [WikiPlugins]: https://github.com/picocms/Pico/wiki/Pico-Plugins [OfficialThemes]: http://picocms.org/themes/