From 1ce4a0bc368a96d16ca836eaea97b67968fdf408 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Sun, 1 Jul 2018 17:16:29 +0200 Subject: [PATCH] Sync user and inline docs --- README.md | 28 +++++++------- content-sample/index.md | 81 +++++++++++++++++++++++++++-------------- 2 files changed, 69 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index da379cf..d4f177c 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,17 @@ Screenshot Install ------- -Installing Pico is dead simple - and done in seconds! If you have access to a shell on your server (i.e. SSH access), we recommend using [composer][]. If not, use a pre-bundled release. If you don't know what "SSH access" is, head over to the pre-bundled release. 😇 +Installing Pico is dead simple - and done in seconds! If you have access to a shell on your server (i.e. SSH access), we recommend using [Composer][]. If not, use a pre-bundled release. If you don't know what "SSH access" is, head over to the pre-bundled release. 😇 Pico requires PHP 5.3.6+ -### I want to use composer +### I want to use Composer -Starting with Pico 2.0 we recommend installing Pico using composer whenever possible. Trust us, you won't regret it when it comes to upgrading Pico! Anyway, if you don't want to use composer, or if you simply can't use composer because you don't have access to a shell on your server, don't despair, installing Pico using a pre-bundled release is still easier than everything you know! +Starting with Pico 2.0 we recommend installing Pico using Composer whenever possible. Trust us, you won't regret it when it comes to upgrading Pico! Anyway, if you don't want to use Composer, or if you simply can't use Composer because you don't have access to a shell on your server, don't despair, installing Pico using a pre-bundled release is still easier than everything you know! ###### Step 1 -Open a shell and navigate to the desired install directory of Pico within the `httpdocs` directory (e.g. `/var/www/html`) of your server. Download composer and run it with the `create-project` option: +Open a shell and navigate to the desired install directory of Pico within the `httpdocs` directory (e.g. `/var/www/html`) of your server. Download Composer and run it with the `create-project` option: ```shell $ curl -sSL https://getcomposer.org/installer | php @@ -42,7 +42,7 @@ What second step? There's no second step. That's it! Open your favorite web brow ### I want to use a pre-bundled release -Do you know the feeling: I want to install a new website, upload all files of my favorite CMS and run the setup script - just to find out that I forgot about creating the SQL database first? Later the setup script tells me that my file permissions are wrong. Heck, what does this even mean? Forget about it, Pico is different! +Do you know the feeling: You want to install a new website, so you upload all files of your favorite CMS and run the setup script - just to find out that you forgot about creating the SQL database first? Later the setup script tells you that the file permissions are wrong. Heck, what does this even mean? Forget about it, Pico is different! ###### Step 1 @@ -54,9 +54,9 @@ Okay, here's the catch: There's no catch. That's it! Open your favorite web brow ### I'm a developer -So, you're one of these amazing folks making all of this possible? We love you guys! As a developer we recommend you to clone [Pico's Git repository][PicoGit] and use composer to install its dependencies. You can find both [Pico][PicoPackagist] and [Pico's composer starter project][PicoComposerPackagist] on [Packagist.org][Packagist]. Using Pico's Git repository is different from using one of the installation methods elucidated above, because it uses Pico as the composer root package. Furthermore it gives you the current development version of Pico, what is likely *unstable* and *not ready for production use*! +So, you're one of these amazing folks making all of this possible? We love you guys! As a developer we recommend you to clone [Pico's Git repository][PicoGit] and use Composer to install its dependencies. You can find both [Pico][PicoPackagist] and [Pico's Composer starter project][PicoComposerPackagist] on [Packagist.org][Packagist]. Using Pico's Git repository is different from using one of the installation methods elucidated above, because it uses Pico as the Composer root package. Furthermore it gives you the current development version of Pico, what is likely *unstable* and *not ready for production use*! -Open a shell and navigate to the desired install directory of Pico within the `httpdocs` directory (e.g. `/var/www/html`) of your server. You can now clone Pico's Git repository, download composer and install Pico's dependencies as follows: +Open a shell and navigate to the desired install directory of Pico within the `httpdocs` directory (e.g. `/var/www/html`) of your server. You can now clone Pico's Git repository, download Composer and install Pico's dependencies as follows: ```shell $ git clone https://github.com/picocms/Pico.git . @@ -67,21 +67,21 @@ $ php composer.phar install Upgrade ------- -Do you remember when you installed Pico? It was ingeniously simple, wasn't it? Upgrading Pico is no difference! The upgrade process differs depending on whether you used [composer][] or a pre-bundled release to install Pico. Please note that you should *always* create a backup of your Pico installation before upgrading! +Do you remember when you installed Pico? It was ingeniously simple, wasn't it? Upgrading Pico is no difference! The upgrade process differs depending on whether you used [Composer][] or a pre-bundled release to install Pico. Please note that you should *always* create a backup of your Pico installation before upgrading! Pico follows [Semantic Versioning 2.0][SemVer] and uses version numbers like `MAJOR`.`MINOR`.`PATCH`. When we update the `PATCH` version (e.g. `2.0.0` to `2.0.1`), we made backwards-compatible bug fixes. If we change the `MINOR` version (e.g. `2.0` to `2.1`), we added functionality in a backwards-compatible manner. Upgrading Pico is dead simple in both cases. Simply head over to the appropiate Upgrade sections below. But wait, we forgot to mention what happens when we update the `MAJOR` version (e.g. `2.0` to `3.0`). In this case we made incompatible API changes. We will then provide a appropriate upgrade tutorial, so please head over to the ["Upgrade" page on our website][HelpUpgrade]. -### I've used composer to install Pico +### I've used Composer to install Pico -Upgrading Pico is dead simple if you've used composer to install Pico. Simply open a shell and navigate to Pico's install directory within the `httpdocs` directory (e.g. `/var/www/html/pico`) of your server. You can now upgrade Pico using just a single command: +Upgrading Pico is dead simple if you've used Composer to install Pico. Simply open a shell and navigate to Pico's install directory within the `httpdocs` directory (e.g. `/var/www/html/pico`) of your server. You can now upgrade Pico using just a single command: ```shell $ php composer.phar update ``` -That's it! composer will automatically update Pico and all plugins and themes you've installed using composer. Please make sure to manually update all plugins and themes you've installed manually. +That's it! Composer will automatically update Pico and all plugins and themes you've installed using Composer. Please make sure to manually update all plugins and themes you've installed manually. ### I've used a pre-bundled release to install Pico @@ -93,7 +93,7 @@ That's it! Now that Pico is up-to-date, you need to update all plugins and theme ### I'm a developer -As a developer you should be up-to-date already... 😉 For the sake of completeness, if you want to upgrade Pico, simply open a shell and navigate to Pico's install directory within the `httpdocs` directory (e.g. `/var/www/html/pico`) of your server. Then pull the latest commits from [Pico's Git repository][PicoGit] and let composer update your dependencies: +As a developer you should be up-to-date already... 😉 For the sake of completeness, if you want to upgrade Pico, simply open a shell and navigate to Pico's install directory within the `httpdocs` directory (e.g. `/var/www/html/pico`) of your server. Then pull the latest commits from [Pico's Git repository][PicoGit] and let Composer update your dependencies: ```shell $ git pull @@ -130,6 +130,8 @@ You want to contribute to Pico? We really appreciate that! You can help make Pic 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 below for more info. + Bounties and Fundraisers ------------------------ @@ -143,7 +145,7 @@ As a developer you can pick up a bounty by simply contributing to Pico (please r 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. -[composer]: https://getcomposer.org/ +[Composer]: https://getcomposer.org/ [LatestRelease]: https://github.com/picocms/Pico/releases/latest [PicoGit]: https://github.com/picocms/Pico [PicoPackagist]: http://packagist.org/packages/picocms/pico diff --git a/content-sample/index.md b/content-sample/index.md index b0f52ea..84f5d01 100644 --- a/content-sample/index.md +++ b/content-sample/index.md @@ -278,39 +278,66 @@ developed a plugin before and want to upgrade it to Pico 2.0, refer to the ## Config -You can override the default Pico settings (and add your own custom settings) -by editing `config/config.yml` in the Pico directory. For a brief overview of -the available settings and their defaults see `config/config.yml.template`. To -override a setting, simply copy the line from `config/config.yml.template` -to `config/config.yml` and set your custom value. Pico will read all `*.yml` -files in the `config/` dir, thus you can even use a distinct settings file to -configure your custom theme (e.g. `config/my_theme.yml`). +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` 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 `%base_url%/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. 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. %base_url%/?sub/page) already are very user-friendly. Additionally, Pico offers you a URL rewrite feature to make URLs even more -user-friendly (e.g. %base_url%/sub/page). +user-friendly (e.g. %base_url%/sub/page). Below you'll find some basic info +about how to configure your webserver proberly to enable URL rewriting. #### Apache 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][ModRewrite]. Assuming the second URL works, but Pico -still shows no rewritten URLs, force URL rewriting by setting -`rewrite_url: true` in your `config/config.yml`. +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 -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`, `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 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 [Nginx configuration docs][NginxConfig]. +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/((config|content|vendor|composer\.(json|lock|phar))(/|$)|(.+/)?\.(?!well-known(/|$))) { @@ -325,13 +352,12 @@ location /pico/ { #### Lighttpd -Pico runs smoothly on Lighttpd. You can use the following configuration 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 configuration below should provide the *bare minimum* -you need for Pico. +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 = ( @@ -358,4 +384,5 @@ For more help have a look at the Pico documentation at http://picocms.org/docs. [OfficialThemes]: http://picocms.org/themes/ [PluginUpgrade]: http://picocms.org/development/#upgrade [ModRewrite]: https://httpd.apache.org/docs/current/mod/mod_rewrite.html +[AllowOverride]: https://httpd.apache.org/docs/current/mod/core.html#allowoverride [NginxConfig]: http://picocms.org/in-depth/nginx/