From 03d475c31c8a6ea3e676c34d93a7908133b4be65 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Mon, 4 Nov 2019 00:36:05 +0100 Subject: [PATCH] Update Pico's sample contents to reflect the changes of Pico 2.1 --- content-sample/_meta.md | 2 +- content-sample/index.md | 225 ++++++++++++++++++++++++---------------- 2 files changed, 139 insertions(+), 88 deletions(-) diff --git a/content-sample/_meta.md b/content-sample/_meta.md index 9cdf202..5a17b8c 100644 --- a/content-sample/_meta.md +++ b/content-sample/_meta.md @@ -1,5 +1,5 @@ --- -social: +Social: - title: Visit us on GitHub url: https://github.com/picocms/Pico icon: octocat diff --git a/content-sample/index.md b/content-sample/index.md index 0a702f7..a6b3389 100644 --- a/content-sample/index.md +++ b/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 -your assets there. You can then access them in your Markdown using -%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 %} -
-

{{ page.title }}

-

{{ page.date_formatted }}

-

{{ page.description }}

-
- {% endif %} + {% for page in pages("blog")|sort_by("time")|reverse if not page.hidden %} +
+

{{ page.title }}

+

{{ page.date_formatted }}

+

{{ page.description }}

+
{% 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: + +
+ {% for page in pages(current_page.id) if not page.hidden %} + + {% endfor %} +
+ +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 %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/