Docs updates for 3.0

.gitignore

@@ -0,0 +1,11 @@
+# Linux
+*~
+*.swp
+
+# Windows
+Thumbs.db
+desktop.ini
+
+# Mac OS X
+.DS_Store
+._*

_docs/config.md

@@ -14,11 +14,11 @@ nav: 5
 
 Configuring Pico really is stupidly simple: Just create a `config/config.yml` to override the default Pico settings (and add your own custom settings). Take a look at the [`config/config.yml.template`][ConfigTemplate] for a brief overview of the available settings and their defaults. To override a setting, simply copy the line from `config/config.yml.template` to `config/config.yml` and set your custom value.
 
-But we didn't stop there. Rather than having just a single config file, you can use a arbitrary number of config files. Simply create a `.yml` file in Pico's `config` dir and you're good to go. This allows you to add some structure to your config, like a separate config file for your theme (`config/my_theme.yml`).
+But we didn't stop there. Rather than having just a single config file, you can use an arbitrary number of config files. Simply create a `.yml` file in Pico's `config` dir, and you're good to go. This allows you to add some structure to your config, like a separate config file for your theme (`config/my_theme.yml`).
 
-Please note that Pico loads config files in a special way you should be aware of. First of all it loads the main config file `config/config.yml`, and then any other `*.yml` file in Pico's `config` dir in alphabetical order. The file order is crucial: Config values which have been set already, cannot be overwritten by a succeeding file. For example, if you set `site_title: Pico` in `config/a.yml` and `site_title: My awesome site!` in `config/b.yml`, your site title will be "Pico".
+Please note that Pico loads config files in a special way you should be aware of. It loads the main config file `config/config.yml`, and then any other `*.yml` file in Pico's `config` dir in alphabetical order. The file order is crucial: Config values which have been set already, cannot be overwritten by a succeeding file. For example, if you set `site_title: Pico` in `config/a.yml` and `site_title: My awesome site!` in `config/b.yml`, your site title will be "Pico".
 
-Since YAML files are plain text files, users might read your Pico config by navigating to `https://example.com/pico/config/config.yml`. This is no problem in the first place, but might get a problem if you use plugins that require you to store security-relevant data in the config (like credentials). Thus you should *always* make sure to configure your webserver to deny access to Pico's `config` dir. Just refer to the ["URL Rewriting" section below][UrlRewriting]. By following the instructions, you will not just enable URL rewriting, but also deny access to Pico's `config` dir.
+Since YAML files are plain text files, users might read your Pico config by navigating to `https://example.com/pico/config/config.yml`. This is no problem in the first place, but might get a problem if you use plugins that require you to store security-relevant data in the config (like credentials). Thus, you should *always* make sure to configure your webserver to deny access to Pico's `config` dir. Just refer to the ["URL Rewriting" section below][UrlRewriting]. By following the instructions, you will not just enable URL rewriting, but also deny access to Pico's `config` dir.
 
 ### URL Rewriting
 

_docs/contributing.md

@@ -8,7 +8,7 @@ nav: 7
 
 You want to contribute to Pico? We really appreciate that! You can help make Pico better by [contributing code][PullRequests] or [reporting issues][Issues], but please take note of our [contribution guidelines][ContributionGuidelines]. In general you can contribute in three different areas:
 
-1. Plugins & Themes: You're a plugin developer or theme designer? We love you guys! You can find tons of information about how to develop plugins and themes at [{{ site.github.url }}/development/][PluginDocs]. If you have created a plugin, feel free to add it to our [plugins][WikiPlugins] wiki page. You may also [Submit][] plugins and themes to our website, where they'll be displayed on the official [plugin][OfficialPlugins] or [theme][OfficialThemes] pages!
+1. Plugins & Themes: You're a plugin developer or theme designer? We love you folks! To get you started with creating a plugin or theme, check out Pico's [`DummyPlugin`][PicoDummyPlugin], and [Pico's default theme][PicoThemeGit]. If you have created a plugin or theme, please add it to our [Wiki][] and [Submit][] it to our website, where it'll be displayed on the official [plugin][OfficialPlugins] or [theme][OfficialThemes] pages!
 
 2. Documentation: We always appreciate people improving our documentation. You can either improve the [inline user docs][EditInlineDocs] or the more extensive [user docs on our website][EditUserDocs]. You can also improve the [docs for plugin and theme developers][EditDevDocs]. Simply fork our website's Git repository from [{{ site.gh_pages_url }}][GitHubWebsite], change the Markdown files and open a [pull request][PullRequestsWebsite].
 
@@ -29,6 +29,8 @@ You don't have time to contribute code to Pico, but still want to "stand a coffe
 [Submit]: {{ site.github.url }}/in-depth/submission_guidelines
 [OfficialPlugins]: {{ site.github.url }}/plugins/
 [OfficialThemes]: {{ site.github.url }}/themes/
+[PicoThemeGit]: https://github.com/picocms/pico-theme
+[PicoDummyPlugin]: https://github.com/picocms/Pico/blob/master/plugins/DummyPlugin.php
 [EditInlineDocs]: {{ site.gh_project_url }}/edit/{{ site.gh_project_branch }}/content-sample/index.md
 [EditUserDocs]: {{ site.gh_pages_url }}/tree/{{ site.gh_pages_branch }}/_docs
 [EditDevDocs]: {{ site.gh_pages_url }}/tree/{{ site.gh_pages_branch }}/_development

_docs/creating-content.md

@@ -45,7 +45,7 @@ If you create a folder within the content directory (e.g. `content/sub`) and put
         </tr>
         <tr>
             <td>content/a/very/long/url.md</td>
-            <td>?a/very/long/url</td>
+            <td>?a/very/long/url (doesn't exist)</td>
         </tr>
     </tbody>
 </table>
@@ -54,13 +54,13 @@ If a file cannot be found, the file `content/404.md` will be shown. You can add
 
 Pico strictly separates contents of your website (the Markdown files in your `content` directory) and how these contents should be displayed (the Twig templates in your `themes` directory). However, not every file in your `content` directory might actually be a distinct page. For example, some themes (including Pico's default theme) use some special "hidden" file to manage meta data (like `_meta.md` in Pico's sample contents). Some other themes use a `_footer.md` to represent the contents of the website's footer. The common point is the `_`: all files and directories prefixed by a `_` in your `content` directory are hidden. These pages can't be accessed from a web browser, Pico will show a 404 error 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, 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%/image.png)`
+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. an image) in one of your content 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%/image.png)`
 
 ### Text File Markup
 
 Text files are marked up using [Markdown][] and [Markdown Extra][MarkdownExtra]. They can also contain regular HTML.
 
-At the top of text files you can place a block comment and specify certain meta attributes of the page using [YAML][] (the "YAML header"). For example:
+At the top of text files you can place a block comment and specify certain meta attributes of the page using [YAML][] (the "YAML Front Matter", or "YAML header"). For example:
 
 <pre><code>---
 Title: Welcome
@@ -71,12 +71,12 @@ Robots: noindex,nofollow
 Template: index
 ---</code></pre>
 
-These values will be contained in the `{% raw %}{{ meta }}{% endraw %}` variable in themes (see below). Meta headers can sometimes have special functions. For example: 
+These values will be contained in the `{% raw %}{{ meta }}{% endraw %}` variable in themes (see below). Meta headers can sometimes have special functions. For example:
 
-- `Date` tells Pico when the page was created, letting you sort your pages not just alphabetically, but by date. 
-- `Template` controls what Twig template Pico uses to display the page. For example, if you add `Template: blog`, Pico uses `blog.twig`.
+- `Date` tells Pico when the page was created, letting you sort your pages not just alphabetically, but by date. Pico furthermore not only passes through the `Date` meta header, but rather evaluates it to really "understand" when this page was created.
+- `Template` controls what Twig template Pico uses to display the page. For example, if you add `Template: blog`, Pico uses `blog.twig` to render this page instead of the default `index.twig`.
 
-You can create your own meta attributes and use them in your content or when modifying a theme. For example, if you create an `Order` attribute, you can set `pages_order_by_meta: Order` and `pages_order_by: meta ` in `config.yml` to sort pages in the navigation menu in a custom order.
+You can even create your own meta attributes and use them in your content or when modifying a theme. For example, if you create an `Order` attribute, you can set `pages_order_by_meta: Order` and `pages_order_by: meta ` in `config.yml` to sort pages in the navigation menu in a custom order.
 
 In an attempt to separate contents and styling, we recommend you to not use inline CSS in your Markdown files. You should rather add appropriate CSS 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](%assets_url%/image.png) {.small}`
 
@@ -89,12 +89,13 @@ There are also certain variables that you can use in your text files:
 * `%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`)
+* `%page_id%`, `%page_url%`, and `%page_path%` - The current page's ID (e.g. `sub/index` for `content/sub/index.md`, `sub/page` for `content/sub/page.md`, …), its URL (`sub` resp. `sub/page` in our examples), or its directory path (`sub` in both examples) respectively
 * `%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`
+* `%config.*%` - Access any scalar config variable, e.g. `%config.theme%` is replaced by `default`
 
 ### Blogging
 
-Pico is not blogging software - but makes it very easy for you to use it as a blog. 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.
+Pico is not blogging software - but makes it very easy for you to use it as a blog. You can find many plugins out there implementing typical blogging features like authentication, tagging, pagination and social plugins. See the "Plugins" section below for details.
 
 If you want to use Pico as a blogging software, you probably want to do something like the following:
 
@@ -103,17 +104,19 @@ If you want to use Pico as a blogging software, you probably want to do somethin
         Put all your blog articles in a separate <code>blog</code> folder in your <code>content</code> directory. All these articles should have a <code>Date</code> meta header.
     </li>
     <li>
-        Create a <code>blog.md</code> or <code>blog/index.md</code> in your <code>content</code> directory. Add <code>Template: blog-index</code> to the YAML header of this page. It will later show a list of all your blog articles (see step 3).
+        Create a <code>blog.md</code> or <code>blog/index.md</code> in your <code>content</code> directory. Add <code>Template: blog</code> to the YAML header of this page. It will later show a list of all your blog articles (see step 3).
     </li>
     <li>
-        Create the new Twig template <code>blog-index.twig</code> (the file name must match the <code>Template</code> meta header from Step 2) in your theme directory. This template probably isn't very different from your default <code>index.twig</code> (i.e. copy <code>index.twig</code>), it will create a list of all your blog articles. Add the following Twig snippet to <code>blog-index.twig</code> near <code>{% raw %}{{ content }}{% endraw %}</code>:
-
-{% raw %}<pre><code>{% for page in pages(&quot;blog&quot;)|sort_by(&quot;time&quot;)|reverse if not page.hidden %}
-    &lt;div class=&quot;post&quot;&gt;
-        &lt;h3&gt;&lt;a href=&quot;{{ page.url }}&quot;&gt;{{ page.title }}&lt;/a&gt;&lt;/h3&gt;
-        &lt;p class=&quot;date&quot;&gt;{{ page.date_formatted }}&lt;/p&gt;
-        &lt;p class=&quot;excerpt&quot;&gt;{{ page.description }}&lt;/p&gt;
-    &lt;/div&gt;
+        Create the new Twig template <code>blog.twig</code> (the file name must match the <code>Template</code> meta header from Step 2) in your theme directory. This template probably isn't very different from your default <code>index.twig</code> (i.e. copy <code>index.twig</code>), it will create a list of all your blog articles. Add the following Twig snippet to <code>blog.twig</code> near <code>{% raw %}{{ content }}{% endraw %}</code>:
+
+{% raw %}<pre><code>{% for page in pages(&quot;blog&quot;)|sort_by(&quot;time&quot;)|reverse %}
+    {% if not page.hidden %}
+        &lt;div class=&quot;post&quot;&gt;
+            &lt;h3&gt;&lt;a href=&quot;{{ page.url }}&quot;&gt;{{ page.title }}&lt;/a&gt;&lt;/h3&gt;
+            &lt;p class=&quot;date&quot;&gt;{{ page.date_formatted }}&lt;/p&gt;
+            &lt;p class=&quot;excerpt&quot;&gt;{{ page.description }}&lt;/p&gt;
+        &lt;/div&gt;
+    {% endif %}
 {% endfor %}</code></pre>{% endraw %}
     </li>
 </ol>