Merge pull request #18 from picocms/pico-2.0

Pico 2.0

README.md

@@ -9,11 +9,11 @@ Technology
 ----------
 
 * GitHub Pages
-    - [Jekyll](http://jekyllrb.com/)
+    - [Jekyll](https://jekyllrb.com/)
 * Theme
     - [Webpaint](http://themes.iki-bir.com/webpaint/multipage/full/) theme by [elemis](http://iki-bir.com)
 * Analytics
-    - [Clicky Analytics](http://getclicky.com)
+    - [Clicky Analytics](https://getclicky.com)
 
 Contact
 -------

_docs/bountysource.md

@@ -0,0 +1,21 @@
+---
+toc:
+    bounties-and-fundraisers: Bounties and Fundraisers
+nav: 8
+---
+
+## Bounties and Fundraisers
+
+Pico uses [Bountysource][] to allow monetary contributions to the project. Bountysource is a crowd funding website that focuses on individual issues and feature requests in Open Source projects using micropayment. Users, or "Backers", can pledge money for fixing a specific issue, implementing new features, or developing a new plugin or theme. Open source software developers, or "Bounty Hunters", can then pick up and solve these tasks to earn the money.
+
+Obviously this won't allow a developer to replace a full time job, it's rather aiming to "stand a coffee". However, it helps bringing users and developers closer together, and shows developers what users want and how much they care about certain things. Nevertheless you can still donate money to the project itself, as an easy way to say "Thank You" and to support Pico.
+
+If you want to encourage developers to [fix a specific issue][Issues] or implement a feature, simply [pledge a new bounty][Bountysource] or back an existing one.
+
+As a developer you can pick up a bounty by simply contributing to Pico (please refer to the "Contributing" section above). You don't have to be a official Pico Contributor! Pico is a Open Source project, anyone can open [pull requests][PullRequests] and claim bounties.
+
+Official Pico Contributors won't claim bounties on their own behalf, Pico will never take any money out of Bountysource. All money collected by Pico is used to pledge new bounties or to support projects Pico depends on.
+
+[Bountysource]: https://www.bountysource.com/teams/picocms
+[Issues]: https://github.com/picocms/Pico/issues
+[PullRequests]: https://github.com/picocms/Pico/pulls

_docs/config.md

@@ -2,43 +2,66 @@
 toc:
     config:
         _title: Config
-        url-rewriting: URL Rewriting
-        apache: Apache
-        nginx: Nginx
-nav: 6
+        url-rewriting:
+            _title: URL Rewriting
+            apache: Apache
+            nginx: Nginx
+            lighttpd: Lighttpd
+nav: 5
 ---
 
 ## 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`][ConfigTemplate]. To override a setting, copy `config/config.php.template` to `config/config.php`, uncomment the setting and set your custom value.
+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`).
+
+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: Configiguration 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.
 
 ### URL Rewriting
 
-Pico's default URLs (e.g. http://example.com/pico/?sub/page) already are very user-friendly. Additionally, Pico offers you a URL rewrite feature to make URLs even more user-friendly (e.g. http://example.com/pico/sub/page).
+Pico's default URLs (e.g. https://example.com/pico/?sub/page) already are very user-friendly. Additionally, Pico offers you a URL rewrite feature to make URLs even more user-friendly (e.g. https://example.com/pico/sub/page). Below you'll find some basic info about how to configure your webserver proberly to enable URL rewriting. For additional assistance, please refer to the ["Getting Help" section][GettingHelp] below.
 
 #### Apache
 
-If you're using the Apache web server, URL rewriting should be enabled automatically. If you get an error message from your web server, please make sure to enable the [`mod_rewrite` module][ModRewrite]. Assuming rewritten URLs work, 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 the Apache web server, URL rewriting should be enabled automatically. If URL rewriting doesn't work (you're getting `404 Not Found` error messages from Apache), please make sure to enable the [`mod_rewrite` module][ModRewrite] and to enable `.htaccess` overrides. You might have to set the [`AllowOverride` directive][AllowOverride] to `AllowOverride All` in your virtual host config file or global `httpd.conf`/`apache.conf`. Assuming rewritten URLs work, but Pico still shows no rewritten URLs, force URL rewriting by setting `rewrite_url: true` in your `config/config.yml`. If you rather get a `500 Internal Server Error` no matter what you do, try removing the `Options` directive from Pico's `.htaccess` file (it's the last line).
 
 #### Nginx [Learn more…][NginxConfig]{:.learn-more}
 {:#nginx}
 
-If you're using Nginx, you can use the following configuration to enable URL rewriting (lines `5` to `8`) and denying access to Pico's internal files (lines `1` to `3`). You'll need to adjust the path (`/pico` on lines `1`, `5` and `7`) to match your installation directory. Additionally, you'll need to enable URL rewriting by setting `$config['rewrite_url'] = true;` in your `config/config.php`.
+If you're using Nginx, you can use the following config to enable URL rewriting (lines `5` to `8`) and denying access to Pico's internal files (lines `1` to `3`). You'll need to adjust the path (`/pico` on lines `1`, `2`, `5` and `7`) to match your installation directory. Additionally, you'll need to enable URL rewriting by setting `rewrite_url: true` in your `config/config.yml`. The Nginx config should provide the *bare minimum* you need for Pico. Nginx is a very extensive subject. If you have any trouble, please read through our [Nginx config docs][NginxConfig].
 
 ```
-location ~ /pico/(\.htaccess|\.git|config|content|content-sample|lib|vendor|CHANGELOG\.md|composer\.(json|lock)) {
-	return 404;
+location ~ ^/pico/((config|content|vendor|composer\.(json|lock|phar))(/|$)|(.+/)?\.(?!well-known(/|$))) {
+    try_files /pico/index.php$is_args$args;
 }
 
-location ~ ^/pico(.*) {
-	index index.php;
-	try_files $uri $uri/ /pico/index.php?$1&$args;
+location /pico/ {
+    index index.php;
+    try_files $uri $uri/ /pico/index.php$is_args$args;
 }
 ```
 
-This configuration should provide the *bare minimum* you need for Pico. Nginx is a very extensive subject. If you have any trouble, please read through our page on [Nginx Configuration][NginxConfig]. For additional assistance, please refer to the ["Getting Help" section][GettingHelp] below.
+#### Lighttpd
+
+Pico runs smoothly on Lighttpd. You can use the following config to enable URL rewriting (lines `6` to `9`) and denying access to Pico's internal files (lines `1` to `4`). Make sure to adjust the path (`/pico` on lines `2`, `3` and `7`) to match your installation directory, and let Pico know about available URL rewriting by setting `rewrite_url: true` in your `config/config.yml`. The config below should provide the *bare minimum* you need for Pico.
+
+```
+url.rewrite-once = (
+    "^/pico/(config|content|vendor|composer\.(json|lock|phar))(/|$)" => "/pico/index.php",
+    "^/pico/(.+/)?\.(?!well-known(/|$))" => "/pico/index.php"
+)
+
+url.rewrite-if-not-file = (
+    "^/pico(/|$)" => "/pico/index.php"
+)
+```
 
-[ConfigTemplate]: {{ site.gh_project_url }}/blob/{{ site.gh_project_branch }}/config/config.php.template
+[ConfigTemplate]: {{ site.gh_project_url }}/blob/{{ site.gh_project_branch }}/config/config.yml.template
+[UrlRewriting]: {{ site.github.url }}/docs/#url-rewriting
 [ModRewrite]: https://httpd.apache.org/docs/current/mod/mod_rewrite.html
+[AllowOverride]: https://httpd.apache.org/docs/current/mod/core.html#allowoverride
 [NginxConfig]: {{ site.github.url }}/in-depth/nginx/
 [GettingHelp]: {{ site.github.url }}/docs/#getting-help

_docs/contribute.md → _docs/contributing.md

@@ -1,22 +1,28 @@
 ---
 toc:
-    contribute: Contribute
-nav: 8
+    contributing: Contributing
+nav: 7
 ---
 
-## Contribute
+## Contributing
 
 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 or theme, please add it to our [Wiki][], either on the [plugins][WikiPlugins] or [themes][WikiThemes] page. You may also [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 Pico from [GitHub][], change the Markdown files and open a [pull request][PullRequests].
+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].
 
-3. Pico's Core: The supreme discipline is to work on Pico's Core. Your contribution should help *every* Pico user to have a better experience with Pico. If this is the case, fork Pico from [GitHub][] and open a [pull request][PullRequests]. We look forward to your contribution!
+3. Pico's Core: The supreme discipline is to work on Pico's Core. Your contribution should help *every* Pico user to have a better experience with Pico. If this is the case, fork Pico from [{{ site.gh_project_url }}][GitHub] and open a [pull request][PullRequests]. We look forward to your contribution!
+
+By contributing to Pico, you accept and agree to the *Developer Certificate of Origin* for your present and future contributions submitted to Pico. Please refer to the ["Developer Certificate of Origin" section in our `CONTRIBUTING.md`][ContributionGuidelinesDCO].
+
+You don't have time to contribute code to Pico, but still want to "stand a coffee" for the ones who do? You can contribute monetary to Pico using [Bountysource][], a crowd funding website that focuses on individual issues and feature requests. Just refer to the ["Bounties and Fundraisers" section][BountysourceDocs] below for more info.
 
 [Issues]: {{ site.gh_project_url }}/issues
 [PullRequests]: {{ site.gh_project_url }}/pulls
+[PullRequestsWebsite]: {{ site.gh_pages_url }}/pulls
 [ContributionGuidelines]: {{ site.gh_project_url }}/blob/{{ site.gh_project_branch }}/CONTRIBUTING.md
+[ContributionGuidelinesDCO]: {{ site.gh_project_url }}/blob/{{ site.gh_project_branch }}/CONTRIBUTING.md#developer-certificate-of-origin
 [PluginDocs]: {{ site.github.url }}/development/
 [Wiki]: {{ site.gh_project_url }}/wiki
 [WikiPlugins]: {{ site.gh_project_url }}/wiki/Pico-Plugins
@@ -28,3 +34,6 @@ You want to contribute to Pico? We really appreciate that! You can help make Pic
 [EditUserDocs]: {{ site.gh_pages_url }}/tree/{{ site.gh_pages_branch }}/_docs
 [EditDevDocs]: {{ site.gh_pages_url }}/tree/{{ site.gh_pages_branch }}/_development
 [GitHub]: {{ site.gh_project_url }}
+[GitHubWebsite]: {{ site.gh_pages_url }}
+[Bountysource]: https://www.bountysource.com/teams/picocms
+[BountysourceDocs]: {{ site.github.url }}/docs/#bounties-and-fundraisers

_docs/creating-content.md

@@ -4,16 +4,16 @@ toc:
         _title: Creating Content
         text-file-markup: Text File Markup
         blogging: Blogging
-nav: 4
+nav: 3
 ---
 
 ## Creating Content
 
 Pico is a flat file CMS. This means there is no administration backend or database to deal with. You simply create `.md` files in the `content` folder and those files become your pages. For example, creating a file called `index.md` will make it show as your main landing page.
 
-When you install Pico, it comes with a `content-sample` folder. Inside this folder is a sample website that will display until you add your own content. You should create your own `content` folder in Pico's root directory and place your files there. No configuration is required, Pico will automatically use the `content` folder if it exists.
+When you install Pico, it comes with a `content-sample` folder. Inside this folder is a sample website that will display until you add your own content. Simply add some `.md` files to your `content` folder in Pico's root directory. No configuration is required, Pico will automatically use the `content` folder as soon as you create your own `index.md`.
 
-If you create a folder within the content folder (e.g. `content/sub`) and put an `index.md` inside it, you can access that folder at the URL `http://example.com/?sub`. If you want another page within the sub folder, simply create a text file with the corresponding name and you will be able to access it (e.g. `content/sub/page.md` is accessible from the URL `http://example.com/?sub/page`). Below we've shown some examples of locations and their corresponding URLs:
+If you create a folder within the content directory (e.g. `content/sub`) and put an `index.md` inside it, you can access that folder at the URL `https://example.com/pico/?sub`. If you want another page within the sub folder, simply create a text file with the corresponding name and you will be able to access it (e.g. `content/sub/page.md` is accessible from the URL `https://example.com/pico/?sub/page`). Below we've shown some examples of locations and their corresponding URLs:
 
 <table style="width: 100%; max-width: 40em;">
     <thead>
@@ -48,7 +48,7 @@ If you create a folder within the content folder (e.g. `content/sub`) and put an
 
 If a file cannot be found, the file `content/404.md` will be shown. You can add `404.md` files to any directory. So, for example, if you wanted to use a special error page for your blog, you could simply create `content/blog/404.md`.
 
-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)`
+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)`
 
 ### Text File Markup
 
@@ -60,12 +60,12 @@ At the top of text files you can place a block comment and specify certain meta
 Title: Welcome
 Description: This description will go in the meta description tag
 Author: Joe Bloggs
-Date: 2013/01/01
+Date: 2001-04-25
 Robots: noindex,nofollow
 Template: index
 ---</code></pre>
 
-These values will be contained in the `{% raw %}{{ meta }}{% endraw %}` variable in themes (see below).
+These values will be contained in the `{% raw %}{{ meta }}{% endraw %}` variable in themes (see below). Meta headers sometimes have a special meaning: For instance, Pico not only passes through the `Date` meta header, but rather evaluates it to really "understand" when this page was created. This comes into play when you want to sort your pages not just alphabetically, but by date. Another example is the `Template` meta header: It controls what Twig template Pico uses to display this page (e.g. if you add `Template: blog`, Pico uses `blog.twig`).
 
 There are also certain variables that you can use in your text files:
 
@@ -79,6 +79,7 @@ There are also certain variables that you can use in your text files:
 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.
 
 If you want to use Pico as a blogging software, you probably want to do something like the following:
+
 <ol>
     <li>
         Put all your blog articles in a separate <code>blog</code> folder in your <code>content</code> directory. All these articles should have both a <code>Date</code> and <code>Template</code> meta header, the latter with e.g. <code>blog-post</code> as value (see Step 2).
@@ -90,7 +91,7 @@ If you want to use Pico as a blogging software, you probably want to do somethin
         Create a <code>blog.md</code> in your <code>content</code> folder and set its <code>Template</code> meta header to e.g. <code>blog</code>. Also create a <code>blog.twig</code> in your theme directory. This template will show a list of your articles, so you probably want to do something like this:
 
         {% raw %}<pre><code>{% for page in pages|sort_by("time")|reverse %}
-    {% if page.id starts with &quot;blog/&quot; %}
+    {% if page.id starts with &quot;blog/&quot; and 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;
@@ -104,6 +105,6 @@ If you want to use Pico as a blogging software, you probably want to do somethin
     </li>
 </ol>
 
-[Markdown]: http://daringfireball.net/projects/markdown/syntax
+[Markdown]: https://daringfireball.net/projects/markdown/syntax
 [MarkdownExtra]: https://michelf.ca/projects/php-markdown/extra/
 [YAML]: https://en.wikipedia.org/wiki/YAML