Update Pico's sample contents to reflect the changes of Pico 2.1
This commit is contained in:
Daniel Rudolf
parent
dec44817a5
commit
03d475c31c
2 changed files with 139 additions and 88 deletions
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
social:
|
||||
Social:
|
||||
- title: Visit us on GitHub
|
||||
url: https://github.com/picocms/Pico
|
||||
icon: octocat
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<code>%base_url%/assets/</code> for example:
|
||||
<code>!\[Image Title\](%base_url%/assets/image.png)</code>
|
||||
files, use Pico's `assets` folder. You can then access them in your Markdown
|
||||
using the <code>%assets_url%</code> placeholder, for example:
|
||||
<code>!\[Image Title\](%assets_url%/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\](%base_url%/assets/image.png) {.small}</code>
|
||||
<code>!\[Image Title\](%assets_url%/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>%base_url%</code> - The URL to your Pico site; internal links
|
||||
can be specified using <code>%base_url%?sub/page</code>
|
||||
* <code>%theme_url%</code> - The URL to the currently used theme
|
||||
* <code>%assets_url%</code> - The URL to Pico's `assets` directory
|
||||
* <code>%themes_url%</code> - The URL to Pico's `themes` directory;
|
||||
don't confuse this with <code>%theme_url%</code>
|
||||
* <code>%plugins_url%</code> - The URL to Pico's `plugins` directory
|
||||
* <code>%version%</code> - Pico's current version string (e.g. `2.0.0`)
|
||||
* <code>%meta.*%</code> - Access any meta variable of the current
|
||||
page, e.g. <code>%meta.author%</code> is replaced with `Joe Bloggs`
|
||||
* <code>%config.*%</code> - Access any scalar config variable,
|
||||
e.g. <code>%config.theme%</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 %}
|
||||
{% if page.id starts with "blog/" and not page.hidden %}
|
||||
<div class="post">
|
||||
<h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
|
||||
<p class="date">{{ page.date_formatted }}</p>
|
||||
<p class="excerpt">{{ page.description }}</p>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% for page in pages("blog")|sort_by("time")|reverse if not page.hidden %}
|
||||
<div class="post">
|
||||
<h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
|
||||
<p class="date">{{ page.date_formatted }}</p>
|
||||
<p class="excerpt">{{ page.description }}</p>
|
||||
</div>
|
||||
{% 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:
|
||||
|
||||
<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.
|
||||
* `{{ 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 <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>%base_url%</code>) in
|
||||
arbitrary strings using the `url` filter. This is helpful together with meta
|
||||
variables, e.g. if you add <code>image: %assets_url%/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
|
||||
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 <code>%meta.*%</code> 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 <code>%meta.*%</code> 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. `<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/
|
||||
|
|
|
|||
Loading…
Reference in a new issue