SeaCMS
/
pico
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source
pico-3.0-alpha
Daniel Rudolf 6 years ago
parent dec44817a5
commit 03d475c31c
No known key found for this signature in database
GPG Key ID: A061F02CD8DE4538
2 changed files with 139 additions and 88 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 2
      content-sample/_meta.md
  2. 215
      content-sample/index.md

2
content-sample/_meta.md
Unescape View File

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

215
content-sample/index.md
Unescape View File

@ -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>&#37;base_url&#37;/assets/</code> for example:
<code>!\[Image Title\](&#37;base_url&#37;/assets/image.png)</code>
files, use Pico's `assets` folder. You can then access them in your Markdown
using the <code>&#37;assets_url&#37;</code> placeholder, for example:
<code>!\[Image Title\](&#37;assets_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 %}
{% if page.id starts with "blog/" and not page.hidden %}
{% 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>
{% endif %}
{% 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>&#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
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>&#37;meta.&#42;&#37;</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>&#37;meta.&#42;&#37;</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/

Write Preview
Loading…
Cancel
Save