From b53031d90d02fc5b58ab778e8002494b67383dd5 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Sun, 24 Jun 2018 18:46:52 +0200 Subject: [PATCH] Various small improvements --- in-depth/nginx.md | 2 +- in-depth/upgrade-pico-20.md | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/in-depth/nginx.md b/in-depth/nginx.md index 3def5199..59732f51 100644 --- a/in-depth/nginx.md +++ b/in-depth/nginx.md @@ -25,7 +25,7 @@ If you are migrating from Apache, [this article](https://www.digitalocean.com/co ## Getting Started -While the [example]({{ site.github.url }}/docs#nginx) provided on the previous page is a good starting point, here we will provide a more in-depth look at Nginx configuration. +While the [example]({{ site.github.url }}/docs/#nginx) provided on the previous page is a good starting point, here we will provide a more in-depth look at Nginx configuration. We've broken down the process of configuring Pico into three segments, in addition to [general server configuration](#general-server-configuration). The three sets of rules we will be developing provide the following functions: [Denying access to Pico's internal files](#denying-access-to-picos-internal-files), [configuring PHP](#php-configuration), and [setting up Pico's URL rewriting](#url-rewriting). Although it's arguably the most important function, we'll be configuring URL rewriting last due to the order that Nginx processes its config. Having this said: The order of your rules do matter in Nginx, so make sure that the rules have the same order as we discuss them in this document. diff --git a/in-depth/upgrade-pico-20.md b/in-depth/upgrade-pico-20.md index 5e1b19e4..eeaf2599 100644 --- a/in-depth/upgrade-pico-20.md +++ b/in-depth/upgrade-pico-20.md @@ -39,7 +39,7 @@ Do you remember when you installed Pico? It was ingeniously simple, wasn't it? U 6. Provided that you're using plugins, copy all of your plugins from the backed `plugins` directory to your Pico installation. Don't copy the outdated files `00-PicoDeprecated.php`, `01-PicoParsePagesContent.php`, `02-PicoExcerpt.php` and `DummyPlugin.php`. Pico 2.0 heavily improves the plugin system and unfortunately also introduces some backwards-incompatible changes. The most important change is that Pico no longer tries to interpret any file in the `plugins` directory as plugin, but this also means that it might ignore a plugin or stumble over a superfluous file. If all of your plugins consist of just a single file (i.e. `plugins/.php`), you're likely good to go. However, if you're copying folders to your `plugins` directory, please note that Pico now only interprets `plugins//.php` as plugin. So make sure to check whether there are updates available for the plugins you use. You might want to take the opportunity to switch to Composer, it makes keeping your plugins up-to-date way easier. Please refer to the ["Pico and Composer, a perfect match" section][UpgradeComposer] below for more details. If one of your plugins stops working after upgrading to Pico 2.0, please refer to the plugin developer - the plugin needs to be updated. You want to know more about the improvements in Pico's plugin system? Just refer to the ["Use Pico's next generation plugin system" section][UpgradePlugins] below. -Please take the opportunity to check whether your webserver is proberly configured, and access to Pico's internal files and dirs is denied. Just refer to the ["URL Rewriting" section in the docs][UrlRewriting]. By following the instructions, you will not just enable URL rewriting, but also deny access to Pico's internal files and dirs. Please note that you should configure your webserver slightly different for Pico 2.0 than for Pico 1.0, so you should update your webserver config no matter what. +Please take the opportunity to check whether your webserver is proberly configured, and access to Pico's internal files and directories is denied. Just refer to the ["URL Rewriting" section in the docs][UrlRewriting]. By following the instructions, you will not just enable URL rewriting, but also deny access to Pico's internal files and directories. Please note that you should configure your webserver slightly different for Pico 2.0 than for Pico 1.0, so you should update your webserver config no matter what. That's the *bare minimum* you need to know when upgrading to Pico 2.0. However, there's way more to know. Thus we highly recommend you to keep reading, the things you'll learn, will not disappoint you! @@ -47,11 +47,11 @@ That's the *bare minimum* you need to know when upgrading to Pico 2.0. However, Configuring Pico is now easier than ever before. Up to this point, Pico used a regular PHP file, the programming language Pico is written in, for its config (`config/config.php`). However, dealing with PHP isn't "stupidly simple", especially for non-developers: It has some pretty strict and unapparent syntax rules, and just the slightest typo results in a PHP error and breaking your whole website. That's not what we want! -For this reason we're happy to anounce YAML config files! As a Pico user you know YAML from the YAML header of your content files, thus it was the obvious choice. But we didn't stop there. Rather than having just a single config file, you can now 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`). +For this reason we're happy to anounce YAML config files! As a Pico user you know YAML from the YAML header of your content files, thus it was the obvious choice. But we didn't stop there. Rather than having just a single config file, you can now use a arbitrary number of config files. Simply create a `.yml` file in Pico's `config` directory 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`). Just take a look at the [`config/config.yml.template`][ConfigTemplate] and create your own config file `config/config.yml`. Even though we still support the old PHP config file (`config/config.php`), we highly recommend you to replace it by a appropiate `config/config.yml`. We will likely drop support of `config/config.php` in Pico's next major release. -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". +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` directory 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 in the docs][UrlRewriting]. By following the instructions, you will not just enable URL rewriting, but also deny access to Pico's `config` dir. @@ -61,6 +61,8 @@ We're pleased to announce that we've incorporated [Composer][] in our work flow, Starting with Pico 2.0 you can (but are not required to!) use Composer to manage your Pico installation. The only thing you need is Shell access to your webserver. You don't have Shell access to your webserver? Don't despair, you can still use Pico's pre-bundled release, and install plugins and themes the same way as with Pico 1.0. However, if you have Shell access to your webserver, we recommend you to use Composer to manage your Pico installation. Trust us, you won't regret it when it comes to upgrading Pico! +Anyway, it's not like you can't change your mind later. Pico's pre-bundled release is basically just a Composer installation packed in a ZIP archive. There's virtually no difference between a pre-bundled release and a Composer installation, both use [`picocms/pico-composer`][PicoComposer] as a basis. + Installing a new plugin or theme is just a single command away. If you want to install e.g. Pico's official [File Prefixes plugin][PicoFilePrefixes], you just have to run `composer require phrozenbyte/pico-file-prefixes` - that's it! You later want to update Pico and all your plugins? Simply run `composer update`. You're a plugin or themes developer, and you want to let your users benefit from this amazing new feature? It's [`picocms/composer-installer`][PicoComposerInstaller] that is responsible for installing plugins and themes. Just add `{ "type": "pico-plugin" }` or `{ "type": "pico-theme" }` to your `composer.json`, and you're ready to go. Please refer to the installer's `README.md` for more info. @@ -115,6 +117,7 @@ Pico 2.0 also introduces some more smaller improvements and changes: * As announced earlier, Pico 2.0 drops the `PicoParsePagesContent` (use the `content` Twig filter instead, e.g. `{% raw %}{{ "sub/page"|content }}{% endraw %}`) and `PicoExcerpt` (use the `description` meta header instead, e.g. `{% raw %}{{ meta.description }}{% endraw %}` in Twig templates or `%meta.description%` in Markdown files) plugins * Pico now uses the relative path between `index.php` and `Pico::$themesDir` when guessing Pico's theme URL * Pico's `.htaccess` file for Apache webservers now includes a directive to deny access to all "dot files" (i.e. files beginning with a `.`, e.g. the `.git` directory) by default; you should update your webserver config if you use another webserver +* Pico's default installation now includes empty `assets` and `content` directories * Pico's official `PicoDeprecated` plugin is no longer maintained in Pico's core repository, but the [`picocms/pico-deprecated` repository][PicoDeprecated] ## Developer News @@ -239,6 +242,7 @@ If you have a question about one of the new features of Pico 2.0, please check o [UrlRewriting]: {{ site.github.url }}/docs/#url-rewriting [FeaturesHttpParams]: {{ site.github.url }}/in-depth/features/http-params/ [FeaturesPageTree]: {{ site.github.url }}/in-depth/features/page-tree/ +[PicoComposer]: https://github.com/picocms/pico-composer [PicoTheme]: https://github.com/picocms/pico-theme [PicoDeprecated]: https://github.com/picocms/pico-deprecated [PicoComposerInstaller]: https://github.com/picocms/composer-installer