From 40dbd0ee373931a11709bdb00f56bae16715278f Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Thu, 8 Oct 2015 21:01:30 +0200 Subject: [PATCH] Update Picos inline user docs Adding a Blogging and URL Rewriting section, splitting the Plugins section into "for users" and "for devs", extend all sections and fix some typos --- content-sample/index.md | 145 ++++++++++++++++++++++++++++++++++------ 1 file changed, 124 insertions(+), 21 deletions(-) diff --git a/content-sample/index.md b/content-sample/index.md index 8ea4d1a..dd2fd2b 100644 --- a/content-sample/index.md +++ b/content-sample/index.md @@ -6,7 +6,7 @@ Description: Pico is a stupidly simple, blazing fast, flat file CMS. ## Welcome to Pico Congratulations, you have successfully installed [Pico](http://picocms.org/). -%meta.description% +%meta.description% ### Creating Content @@ -54,7 +54,9 @@ and their corresponing URLs: -If a file cannot be found, the file `content-sample/404.md` will be shown. +If a file cannot be found, the file `content-sample/404.md` will be shown. You +can add `404.md` files to any directory, so if you want to use a special error +page for your blog, simply create `content-sample/blog/404.md`. ### Text File Markup @@ -81,26 +83,68 @@ There are also certain variables that you can use in your text files: can be specified using %base_url%?sub/page * %theme_url% - The URL to the currently used theme * %meta.*% - Access any meta variable of the current page, - e.g. %meta.author% returns `Joe Bloggs` + e.g. %meta.author% is replaced with `Joe Bloggs` + +### Blogging + +Pico is no blogging software - but makes it very easy for you to use it as a +blogging software. You can find many plugins out there implementing typical +blogging features like authentication, tagging, pagination and social plugins. +See the below Plugins section for details. + +If you want to use Pico as a blogging software, you probably want to do +something like the following: +1. Put all your blog articles in a separate `blog` folder in your `content` + directory. All these articles should have both a `Date` and `Template` meta + header, the latter with e.g. `blog-post` as value (see Step 2). +2. Create a new Twig template called `blog-post.twig` (this must match the + `Template` meta header from Step 1) in your theme directory. This template + probably isn't very different from your default `index.twig`, it specifies + how your article pages will look like. +3. Create a `blog.md` in your `content` folder and set its `Template` meta + header to e.g. `blog`. Also create a `blog.twig` in your theme directory. + This template will show a list of your articles, so you probably want to + do something like this: + ``` + {% for page in pages %} + {% if page.id starts with "blog/" %} +
+

{{ page.title }}

+

{{ page.date_formatted }}

+

{{ page.description }}

+
+ {% endif %} + {% endfor %} + ``` +4. Let Pico sort pages by date by setting `$config['pages_order_by'] = 'date';` + in your `config/config.php`. To use a descending order (newest articles + first), also add `$config['pages_order'] = 'desc';`. The former won't affect + pages without a `Date` meta header, but the latter does. To use ascending + order for your page navigation again, add Twigs `reverse` filter to the + navigation loop (`{% for page in pages|reverse %}...{% endfor %}`) in your + themes `index.twig`. +5. Make sure to exclude the blog articles from your page navigation. You can + achieve this by adding `{% if not page starts with "blog/" %}...{% endif %}` + to the navigation loop. ### Themes You can create themes for your Pico installation in the `themes` folder. Check -out the default theme for an example of a theme. Pico uses [Twig][] for -template rendering. You can select your theme by setting the `$config['theme']` -variable in `config/config.php` to your theme folder. +out the default theme for an example. Pico uses [Twig][] for template +rendering. You can select your theme by setting the `$config['theme']` option +in `config/config.php` to the name of your theme folder. -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. Paths (e.g. `{{ base_dir }}``) and URLs (e.g. `{{ base_url }}`) don't -have a trailing slash. +All themes must include an `index.twig` (or `index.html`) 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. * `{{ config }}` - Conatins the values you set in `config/config.php` - (e.g. `{{ config.theme }}` = "default") + (e.g. `{{ config.theme }}` becomes `default`) * `{{ base_dir }}` - The path to your Pico root directory * `{{ base_url }}` - The URL to your Pico site -* `{{ theme_dir }}` - The path to the Pico active theme directory -* `{{ theme_url }}` - The URL to the Pico active theme directory +* `{{ theme_dir }}` - The path to the currently active theme +* `{{ theme_url }}` - The URL to the currently active theme * `{{ rewrite_url }}` - A boolean flag indicating enabled/disabled URL rewriting * `{{ site_title }}` - Shortcut to the site title (see `config/config.php`) * `{{ meta }}` - Contains the meta values from the current page @@ -109,7 +153,9 @@ have a trailing slash. * `{{ meta.author }}` * `{{ meta.date }}` * `{{ meta.date_formatted }}` + * `{{ meta.time }}` * `{{ meta.robots }}` + * ... * `{{ 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 @@ -128,24 +174,81 @@ have a trailing slash. * `{{ next_page }}` - The data of the next page (relative to `current_page`) * `{{ is_front_page }}` - A boolean flag for the front page -Pages can be used like: +Pages can be used like the following: -
<ul class="nav">
-    {% for page in pages %}
-    <li><a href="{{ page.url }}">{{ page.title }}</a></li>
-    {% endfor %}
-</ul>
+ + +You can use different templates for different content files by specifing the +`Template` meta header. Simply add e.g. `Template: blog-post` to a content file +and Pico will use the `blog-post.twig` file in your theme folder to render +the page. + +You don't have to create your own theme if Picos default theme isn't sufficient +for you, 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](https://github.com/picocms/Pico/wiki/Pico-Themes). ### Plugins -See [http://pico.dev7studios.com/plugins](http://picocms.org/plugins) +#### Plugins for users + +Officially tested plugins can be found at http://pico.dev7studios.com/plugins, +but there are many awesome third-party plugins out there! A good start point +for discovery is [our Wiki](https://github.com/picocms/Pico/wiki/Pico-Plugins). + +Pico makes it very easy for you to add new features to your website. Simply +upload the files of the plugin to the `plugins/` directory and you're done. +Depending on the plugin you've installed, you may have to go through some more +steps (e.g. specifing config variables), the plugin docs or `README` file will +explain what to do. + +Plugins which were written to work with Pico 1.0 can be enabled and disabled +through your `config/config.php`. If you want to e.g. disable the `PicoExcerpt` +plugin, add the following line to your `config/config.php`: +`$config['PicoExcerpt.enabled'] = false;`. To force the plugin to be enabled +replace `false` with `true`. + +#### Plugins for developers + +You're a plugin developer? We love you guys! You can find tons of information +about how to develop plugins at http://picocms.org/plugin-dev.html. If you'd +developed a plugin for Pico 0.9 and older, you probably want to upgrade it +to the brand new plugin system introduced with Pico 1.0. Please refer to the +[Upgrade section of the docs](http://picocms.org/plugin-dev.html#upgrade). + +### URL Rewriting + +Picos default URLs (e.g. %base_url%/?sub/page) already are very user friendly. +Pico anyway offers you an URL rewrite feature to make URLs even more user +friendly (e.g. %base_url%/sub/page). + +If you're using the Apache web server, URL rewriting probably already is +enabled - try it yourself, click on the [second URL](%base_url%/sub/page). If +you get an error message from your web server, please make sure to enable the +`mod_rewrite` module. Assumed the second URL works, but Pico still shows no +rewritten URLs, force URL rewriting by setting `$config['rewrite_url'] = true;` +in your `config/config.php`. + +If you're using Nginx, you can use the following configuration to enable +URL rewriting. Don't forget to adjust the path (`/pico/`; line `1` and `4`) +to match your installation directory. You can then enable URL rewriting by +setting `$config['rewrite_url'] = true;` in your `config/config.php`. + + location /pico/ { + index index.php; + try_files $uri $uri/ /pico/?$uri&$args; + } ### Config You can override the default Pico settings (and add your own custom settings) by editing `config/config.php` in the Pico directory. For a brief overview of the available settings and their defaults see `config/config.php.template`. To -override a setting copy `config/config.php.template` to `config/config.php`, +override a setting, copy `config/config.php.template` to `config/config.php`, uncomment the setting and set your custom value. ### Documentation