Update Pico's sample contents to reflect the changes of Pico 2.1

content-sample/_meta.md

@@ -1,5 +1,5 @@
 ---
-social:
+Social:
     - title: Visit us on GitHub
       url: https://github.com/picocms/Pico
       icon: octocat

content-sample/index.md

@@ -85,10 +85,9 @@ page instead.
 As a common practice, we recommend you to separate your contents and assets
 (like images, downloads, etc.). We even deny access to your `content` directory
 by default. If you want to use some assets (e.g. a image) in one of your content
-files, you should create an `assets` folder in Pico's root directory and upload
+files, use Pico's `assets` folder. You can then access them in your Markdown
-your assets there. You can then access them in your Markdown using
+using the <code>&#37;assets_url&#37;</code> placeholder, for example:
-<code>&#37;base_url&#37;/assets/</code> for example:
+<code>!\[Image Title\](&#37;assets_url&#37;/assets/image.png)</code>
-<code>!\[Image Title\](&#37;base_url&#37;/assets/image.png)</code>
 
 ### 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:
-<code>!\[Image Title\](&#37;base_url&#37;/assets/image.png) {.small}</code>
+<code>!\[Image Title\](&#37;assets_url&#37;/image.png) {.small}</code>
 
 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:
 * <code>&#37;base_url&#37;</code> - The URL to your Pico site; internal links
   can be specified using <code>&#37;base_url&#37;?sub/page</code>
 * <code>&#37;theme_url&#37;</code> - The URL to the currently used theme
+* <code>&#37;assets_url&#37;</code> - The URL to Pico's `assets` directory
+* <code>&#37;themes_url&#37;</code> - The URL to Pico's `themes` directory;
+  don't confuse this with <code>&#37;theme_url&#37;</code>
+* <code>&#37;plugins_url&#37;</code> - The URL to Pico's `plugins` directory
 * <code>&#37;version&#37;</code> - Pico's current version string (e.g. `2.0.0`)
 * <code>&#37;meta.&#42;&#37;</code> - Access any meta variable of the current
   page, e.g. <code>&#37;meta.author&#37;</code> is replaced with `Joe Bloggs`
+* <code>&#37;config.&#42;&#37;</code> - Access any scalar config variable,
+  e.g. <code>&#37;config.theme&#37;</code> 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 %}
+    {% for page in pages("blog")|sort_by("time")|reverse if not page.hidden %}
-        {% if page.id starts with "blog/" and not page.hidden %}
+        <div class="post">
-            <div class="post">
+            <h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
-                <h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
+            <p class="date">{{ page.date_formatted }}</p>
-                <p class="date">{{ page.date_formatted }}</p>
+            <p class="excerpt">{{ page.description }}</p>
-                <p class="excerpt">{{ page.description }}</p>
+        </div>
-            </div>
-        {% endif %}
     {% endfor %}
    ```
 
@@ -179,75 +182,58 @@ details.
 
 ### Themes
 
-You can create themes for your Pico installation in the `themes` folder. Check
+You can create themes for your Pico installation in the `themes` folder. Pico
-out the default theme for an example. Pico uses [Twig][] for template
+uses [Twig][] for template rendering. You can select your theme by setting the
-rendering. You can select your theme by setting the `theme` option in
+`theme` option in `config/config.yml` to the name of your theme folder.
-`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
+the theme, and a `pico-theme.yml` to set the necessary config parameters. Just
-theme. Please note that paths (e.g. `{{ base_dir }}`) and URLs
+refer to Pico's default theme as an example. You can use different templates
-(e.g. `{{ base_url }}`) don't have a trailing slash.
+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.title }}` - The `Title` YAML header
-    * `{{ meta.description }}`
+    * `{{ meta.description }}` - The `Description` YAML header
-    * `{{ meta.author }}`
+    * `{{ meta.author }}` - The `Author` YAML header
-    * `{{ meta.date }}`
+    * `{{ meta.date }}` - The `Date` YAML header
-    * `{{ meta.date_formatted }}`
+    * `{{ meta.date_formatted }}` - The formatted date of the page as specified
-    * `{{ meta.time }}`
+                                    by the `date_format` parameter in your
-    * `{{ meta.robots }}`
+                                    `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
+* `{{ prev_page }}` - The data of the previous page, relative to `current_page`
-    * `{{ page.id }}` - The relative path to the content file (unique ID)
+* `{{ current_page }}` - The data of the current page; refer to the "Pages"
-    * `{{ page.url }}` - The URL to the page
+                         section below for details
-    * `{{ page.title }}` - The title of the page (YAML header)
+* `{{ next_page }}` - The data of the next page, relative to `current_page`
-    * `{{ 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:
-
-    <ul class="nav">
-        {% for page in pages if not page.hidden %}
-            <li><a href="{{ page.url }}">{{ page.title }}</a></li>
-        {% endfor %}
-    </ul>
-
-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.
 
 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
+Please note that Twig escapes HTML in all strings before outputting them. So
-provides some useful additional filters to make theming easier.
+for example, if you add `headline: My <strong>favorite</strong> color` to the
+YAML header of your page and output it using `{{ meta.headline }}`, you'll end
+up seeing `My <strong>favorite</strong> color` - yes, including the markup! To
+actually get it parsed, you must use `{{ meta.headline|raw }}` (resulting in
+the expected <code>My **favorite** color</code>). 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:
+
+    <section class="articles">
+        {% for page in pages(current_page.id) if not page.hidden %}
+            <article>
+                <h2><a href="{{ page.url }}">{{ page.title }}</a></h2>
+                {{ page.id|content }}
+            </article>
+        {% endfor %}
+    </section>
+
+The `pages()` function is very powerful and also allows you to return not just
+a page's child pages by passing the `depth`, `depthOffset` and `offset` params.
+For example, if you pass `pages(depthOffset=-1)`, the list will also include
+Pico's main index page (i.e. `content/index.md`). This one is commonly used to
+create a theme's main navigation. If you want to learn more, head over to
+Pico's complete [`pages` function documentation][FeaturesPagesFunction].
+
+#### Twig filters and functions
+
+Additional to [Twig][]'s extensive list of filters, functions and tags, Pico
+also provides some useful additional filters and functions to make theming
+even easier.
 
 * Pass the unique ID of a page to the `link` filter to return the page's URL
   (e.g. `{{ "sub/page"|link }}` gets `%base_url%?sub/page`).
+* You can replace URL placeholders (like <code>&#37;base_url&#37;</code>) in
+  arbitrary strings using the `url` filter. This is helpful together with meta
+  variables, e.g. if you add <code>image: &#37;assets_url&#37;/stock.jpg</code>
+  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
+* You can parse any Markdown string using the `markdown` filter. For example,
-  use Markdown in the `description` meta variable and later parse it in your
+  you might use Markdown in the `description` meta variable and later parse it
-  theme using `{{ meta.description|markdown }}`). You can pass meta data as
+  in your theme using `{{ meta.description|markdown }}`. You can also pass meta
-  parameter to replace <code>&#37;meta.&#42;&#37;</code> placeholders (e.g.
+  data as parameter to replace <code>&#37;meta.&#42;&#37;</code> placeholders
-  `{{ "Written *by %meta.author%*"|markdown(meta) }}` yields "Written by
+  (e.g. `{{ "Written by *%meta.author%*"|markdown(meta) }}` yields "Written by
-  *John Doe*").
+  *John Doe*"). However, please note that all contents will be wrapped inside
+  HTML paragraph elements (i.e. `<p>…</p>`). 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/