diff --git a/_docs/config.md b/_docs/config.md index 81d760c..37b662a 100644 --- a/_docs/config.md +++ b/_docs/config.md @@ -10,7 +10,7 @@ nav: 4 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 +the available settings and their defaults see [config/config.php.template](https://github.com/picocms/Pico/blob/master/config/config.php.template). To override a setting, copy `config/config.php.template` to `config/config.php`, uncomment the setting and set your custom value. diff --git a/_docs/contribute.md b/_docs/contribute.md index 8067c3f..f6fb746 100644 --- a/_docs/contribute.md +++ b/_docs/contribute.md @@ -8,6 +8,6 @@ nav: 6 Are you are interested in contributing to the development of Pico? -For the basics of creating a **plugin**, **theme** or even contributing to the **Pico core**, we've setup a comprehensive set of [development documentation](/plugin-dev.html) to get you started. +For the basics of creating a __plugin__, __theme__ or even contributing to the __Pico core__, we've setup a comprehensive set of [development documentation]({{ site.base_url }}/plugin-dev.html) to get you started. -You may also see our [class documentation]({{ site.base_url }}/phpDoc/master) for a deeper understanding of Pico's underlying code. +You may also refer to our [class documentation]({{ site.base_url }}/phpDoc/master) for a deeper understanding of Pico's underlying code. diff --git a/_docs/creating-content.md b/_docs/creating-content.md index 4fce2a8..41f049a 100644 --- a/_docs/creating-content.md +++ b/_docs/creating-content.md @@ -20,7 +20,7 @@ and put an `index.md` inside it, you can access that folder at the URL simply create a text file with the corresponding name and you will be able to access it (e.g. `content-sample/sub/page.md` is accessible from the URL `http://yoursite.com/?sub/page`). Below we've shown some examples of locations -and their corresponing URLs: +and their corresponding URLs: @@ -61,7 +61,7 @@ page for your blog, simply create `content-sample/blog/404.md`. ### Text File Markup -Text files are marked up using [Markdown][]. They can also contain regular HTML. +Text files are marked up using [Markdown](https://daringfireball.net/projects/markdown/). They can also contain regular HTML. At the top of text files you can place a block comment and specify certain attributes of the page. For example: @@ -142,6 +142,4 @@ something like the following: -[Markdown]: http://daringfireball.net/projects/markdown/syntax - --- diff --git a/_docs/customization.md b/_docs/customization.md index 8c35b38..d667471 100644 --- a/_docs/customization.md +++ b/_docs/customization.md @@ -10,7 +10,7 @@ nav: 3 ## Customization Pico is highly customizable in two different ways: On the one hand you can -change Picos apperance by using themes, on the other hand you can add new +change Picos appearance by using themes, on the other hand you can add new functionality by using plugins. Doing the former includes changing Picos HTML, CSS and JavaScript, the latter mostly consists of PHP programming. @@ -24,7 +24,7 @@ details. ### Themes You can create themes for your Pico installation in the `themes` folder. Check -out the default theme for an example. Pico uses [Twig][] for template +out the default theme for an example. Pico uses [Twig](http://twig.sensiolabs.org/documentation) 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. @@ -33,7 +33,7 @@ HTML structure of the theme. Below are the Twig variables that are available to use in your theme. Please note that paths (e.g. `{% raw %}{{ base_dir }}{% endraw %}`) and URLs (e.g. `{% raw %}{{ base_url }}{% endraw %}`) don't have a trailing slash. -* `{% raw %}{{ config }}{% endraw %}` - Conatins the values you set in `config/config.php` +* `{% raw %}{{ config }}{% endraw %}` - Contains the values you set in `config/config.php` (e.g. `{% raw %}{{ config.theme }}{% endraw %}` becomes `default`) * `{% raw %}{{ base_dir }}{% endraw %}` - The path to your Pico root directory * `{% raw %}{{ base_url }}{% endraw %}` - The URL to your Pico site; use Twigs `link` filter to @@ -79,7 +79,7 @@ Pages can be used like the following: {% endfor %} </ul>{% endraw %} -You can use different templates for different content files by specifing the +You can use different templates for different content files by specifying 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. @@ -95,18 +95,18 @@ designers created in the past. As with plugins, you can find themes in #### Plugins for users -Officially tested plugins can be found at http://pico.dev7studios.com/plugins, +Officially tested plugins can be found at [http://picocms.com/plugins]({{ site.base_url }}/plugins.html), 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 +steps (e.g. specifying 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` +through your `config/config.php`. If you want to e.g. disable the [PicoExcerpt](https://github.com/picocms/Pico/blob/master/plugins/02-PicoExcerpt.php) 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`. @@ -114,11 +114,9 @@ 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 +about how to develop plugins at [http://picocms.org/plugin-dev.html]({{ site.base_url }}/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). - -[Twig]: http://twig.sensiolabs.org/documentation +[Upgrade section of the docs]({{ site.base_url }}/plugin-dev.html#migrating-from-0x-to-10). --- diff --git a/_docs/install.md b/_docs/install.md index 0efa7b6..a76296f 100644 --- a/_docs/install.md +++ b/_docs/install.md @@ -27,7 +27,7 @@ Open a shell and navigate to the desired install directory of Pico within the `h Please note that this gives you the current development version of Pico, what is likely *unstable* and *not ready for production use*! #### Step 2 -Download [composer][] and run it with the `install` option: +Download [composer][composer] and run it with the `install` option: 
$ curl -sS https://getcomposer.org/installer | php
 $ php composer.phar install
@@ -37,7 +37,7 @@ Pico is available on [Packagist.org](http://packagist.org/packages/picocms/pico) ## Run -You have nothing to consider specially, simply navigate to your Pico install using your favourite web browser. Picos default contents will explain how to use your brand new, stupidly simple, blazing fast, flat file CMS. +You have nothing to consider specially, simply navigate to your Pico install using your favorite web browser. Picos default contents will explain how to use your brand new, stupidly simple, blazing fast, flat file CMS. ### You don't have a web server? diff --git a/_docs/upgrade.md b/_docs/upgrade.md index 4bcf96f..6787dee 100644 --- a/_docs/upgrade.md +++ b/_docs/upgrade.md @@ -18,23 +18,23 @@ Detailed below is some of the most important changes to note when upgrading Pico --- ### Initialization -Initialization of Pico now works completely different: rather than defining constants (which are probably conflicting with other applications...), Pico now expects its paths to be passed as parameters to the constructor. The constructor doesn't start Picos processing anymore, you now have to call the `Pico::run()` method, which returns the parsed page contents instead of directly echoing them. The `PicoDeprecated` plugin defines the now deprecated constants `ROOT_DIR`, `LIB_DIR` etc., so old plugins can still use them. Those constants are defined before reading `config.php` in Picos root folder, so upgrading users usually aren't bothered with e.g. a `PHP Notice: Use of undefined constant ROOT_DIR - assumed 'ROOT_DIR'` error when using `ROOT_DIR` in their `config.php` (so: no BC break). +Initialization of Pico now works completely different: rather than defining constants (which are probably conflicting with other applications...), Pico now expects its paths to be passed as parameters to the [constructor]({{ site.base_url }}/phpDoc/master/classes/Pico.html#method___construct). The constructor doesn't start Picos processing anymore, you now have to call the [Pico::run()]({{ site.base_url }}/phpDoc/master/classes/Pico.html#method_run) method, which returns the parsed page contents instead of directly echoing them. The [PicoDeprecated](https://github.com/picocms/Pico/blob/master/plugins/00-PicoDeprecated.php) plugin defines the now deprecated constants `ROOT_DIR`, `LIB_DIR` etc., so old plugins can still use them. Those constants are defined before reading `config.php` in Picos root folder, so upgrading users usually aren't bothered with e.g. a `PHP Notice: Use of undefined constant ROOT_DIR - assumed 'ROOT_DIR'` error when using `ROOT_DIR` in their `config.php` (so: no BC break). This change is reflected in the new [index.php](https://github.com/picocms/Pico/blob/master/index.php) file. -New users don't need the constants anymore, relative paths are now always interpreted to be relative to Picos root dir, so `$config['content_dir'] = 'content';` is always sufficient (previously this was depending on the webserver config). All these changes are supposed to improve Picos interoperability with other applications and allows developers to integrate Pico in other applications, therefore there is a newly added `Pico::setConfig()` method to even make the use of a config.php optional. +New users don't need the constants anymore, relative paths are now always interpreted to be relative to Picos root dir, so `$config['content_dir'] = 'content';` is always sufficient (previously this was depending on the webserver config). All these changes are supposed to improve Picos interoperability with other applications and allows developers to integrate Pico in other applications, therefore there is a newly added [Pico::setConfig()]({{ site.base_url }}/phpDoc/master/classes/Pico.html#method_setConfig) method to even make the use of a config.php optional. --- ### Routing System -The new routing system now works out-of-the-box (even without rewriting) with any webserver using the QUERY_STRING routing method. Internal links now look like `?sub/page`, rewriting to basically remove the `?` is still possible and recommended. Contrary to Pico 0.9 every webserver should work just fine. Pico 0.9 required working URL rewriting, so if you want to use old plugins/themes/contents, a working rewrite setup may still be required. If you're not using the default .htaccess, you must update your rewrite rules to follow the new principles. Internal links in content files are declared with `%base_url%?sub/page`. Internal links in templates should be declared using the new link filter (e.g. `{{ "sub/page"|link }}`), what basically calls `Pico::getPageUrl()` +The new routing system now works out-of-the-box (even without rewriting) with any webserver using the QUERY_STRING routing method. Internal links now look like `?sub/page`, rewriting to basically remove the `?` is still possible and recommended. Contrary to Pico 0.9 every webserver should work just fine. Pico 0.9 required working URL rewriting, so if you want to use old plugins/themes/contents, a working rewrite setup may still be required. If you're not using the default .htaccess, you must update your rewrite rules to follow the new principles. Internal links in content files are declared with `%base_url%?sub/page`. Internal links in templates should be declared using the new link filter (e.g. `{{ "sub/page"|link }}`), what basically calls [Pico::getPageUrl()]({{ site.base_url }}/phpDoc/master/classes/Pico.html#method_getPageUrl) --- ### Plugin System -A whole new plugin system has been implemented while maintaining full backward compatibility. See the class docs of `IPicoPlugin` for details. The new event system supports plugin dependencies as well as some new events. It was necessary to reliably distinct between old and new events, so __all events were renamed__. The new `PicoDeprecated` plugin is crucial for backward compatibility, it's enabled on demand. Refer to its class docs for details. +A whole new plugin system has been implemented while maintaining full backward compatibility. See the class docs of [PicoPluginInterface]({{ site.base_url }}/phpDoc/master/classes/PicoPluginInterface.html) for details. The new event system supports plugin dependencies as well as some new events. It was necessary to reliably distinct between old and new events, so __all events were renamed__. The new [PicoDeprecated](https://github.com/picocms/Pico/blob/master/plugins/00-PicoDeprecated.php) plugin is crucial for backward compatibility, it's enabled on demand. Refer to its class docs for details. -It is important to note the performance issue with Pico 0.x releases is fixed only when the `PicoParsePagesContent` plugin isn't enabled. It's disabled by default, but gets automatically enabled with `PicoDeprecated` as soon as an old plugin is loaded. This is necessary to maintain backward compatibility. You can still disable it manually by executing` $pico->getPlugin('PicoParsePagesContent')->setEnabled(false);` or adding `$config['PicoParsePagesContent.enabled'] = false;` to your `config.php`. +It is important to note the performance issue with Pico 0.x releases is fixed only when the [PicoParsePagesContent](https://github.com/picocms/Pico/blob/master/plugins/01-PicoParsePagesContent.php) plugin isn't enabled. It's disabled by default, but gets automatically enabled with [PicoDeprecated](https://github.com/picocms/Pico/blob/master/plugins/00-PicoDeprecated.php) as soon as an old plugin is loaded. This is necessary to maintain backward compatibility. You can still disable it manually by executing` $pico->getPlugin('PicoParsePagesContent')->setEnabled(false);` or adding `$config['PicoParsePagesContent.enabled'] = false;` to your `config.php`. ->If you're a plugin developer, please refer to the new development docs, particularly the [plugin upgrade](/plugin-dev.html#migrating-from-0x---10) section. +>If you're a plugin developer, please refer to the new development docs, particularly the [plugin upgrade]({{ site.base_url }}/plugin-dev.html#migrating-from-0x-to-10) section. >Users, please refer to the websites of the plugins you're using to get updates for them. @@ -52,19 +52,19 @@ Usually you don't have to consider anything special, nevertheless you should alw --- #### 1. The first step is to delete all of Picos files except for your __`content`__ directory, __`config.php`__ (or `config/config.php`) and, if applicable, the directory of your custom __`theme`__, and provided that you're using plugins, also keep the __`plugins`__ directory. -![Step 1](style/images/docs/pico_upgrade_delete_old.jpg) -![Step 1a](style/images/docs/pico_upgrade_old_deleted.jpg) +![Step 1]({{ site.base_url }}/style/images/docs/pico_upgrade_delete_old.jpg) +![Step 1a]({{ site.base_url }}/style/images/docs/pico_upgrade_old_deleted.jpg) --- #### 2. You can then upload `Pico 1.0.0` to your installation directory. -![Step 2](style/images/docs/pico_upgrade_select_1.0.jpg) -![Step 2a](style/images/docs/pico_upgrade_move_1.0.jpg) +![Step 2]({{ site.base_url }}/style/images/docs/pico_upgrade_select_1.0.jpg) +![Step 2a]({{ site.base_url }}/style/images/docs/pico_upgrade_move_1.0.jpg) --- #### 3. Move your `config.php` to the new `config/` directory. -![Step 3](style/images/docs/pico_upgrade_move_config.jpg) +![Step 3]({{ site.base_url }}/style/images/docs/pico_upgrade_move_config.jpg) --- @@ -78,10 +78,6 @@ Further reading: --- #### 5. That's it! Enjoy your newly upgraded Pico installation! -If you need more help, please review the documentation. If after reviewing the upgrade documentation, you are still having trouble: there is a __[Upgrading Pico 0.x to 1.0.0]()__ discussion on our Github issues page. - ---- - -TODO: describe how to force enable/disable PicoExcerpt and PicoParsePagesContent +If you need more help, please review the documentation. If after reviewing the upgrade documentation, you are still having trouble: there is a __[Upgrading Pico 0.x to 1.0.0](https://github.com/picocms/Pico/issues/)__ discussion on our Github issues page. --- diff --git a/_plugin-dev/basics.md b/_plugin-dev/basics.md index 833ab08..ff9c301 100644 --- a/_plugin-dev/basics.md +++ b/_plugin-dev/basics.md @@ -7,74 +7,6 @@ nav: 1 # Basics Creating your own content for Pico is *easy*. -Inside the root Pico folder, all *themes* reside in the `themes` directory, and all *plugins* in the `plugins` directory. - -If you want to contribute to Picos core please refer to our [CONTRIBUTING.md](https://github.com/picocms/Pico/blob/master/CONTRIBUTING.md) on GitHub. - -Note that if you are submitting pull requests they should be small (i.e. one feature per request), stick to existing coding conventions and documentation should be updated if required. - ---- - -# Versioning -Pico uses Semantic Versioning. Given a version number MAJOR.MINOR.PATCH, increment the: - -- MAJOR version when you make incompatible API changes, -- MINOR version when you add functionality in a backwards-compatible manner, and -- PATCH version when you make backwards-compatible bug fixes. - -For more information see the [http://semver.org](http://semver.org) website. - ---- - -# Branches -The `master` branch contains the current development version of Pico, -*it is likely unstable and __not ready__ for production use*. - -When creating a new development branch, please follow this prefixing convention: - -- `feature/` for bigger features, -- `enhancement/` for smaller improvements, and -- `bugfix/` for bug fixes. - -As soon as development reaches a point where feedback is appreciated, a PR is opened. After some time (very soon for bug fixes, and other improvements should have a reasonable feedback phase) the PR is merged into `master` and the development branch can be deleted. - ---- - -# Build & Release -Defined below is a specification to which the Build and Release process of Pico should follow. We use `travis-ci` to automate the process, and each commit to `master` should be releasable. - -### Commit phase -- Commit changes -- Create & Push Git tag -- Trigger automatic build process... - -Example commit message: - - Pico 1.0.1 - * [New] ... - * [Changed] ... - -*Please submit pull-requests with a properly -formatted commit message/SemVer increase to avoid the need for manual amendments.* - -### Analysis phase -- Run through `scrutinizer-ci`? - -### Packaging phase -- Run composer locally -- Create a ZIP archive (so vendor/ is included) -- Build documentation, output goes to a new folder in the `gh-pages` branch - -### Release phase -- Create new Git release at tag -- Upload ZIP archive -- Upload documentation to the `gh-pages` branch -- Set Symlink for latest documentation (http://picocms.org/docs/latest) -- Update release information on GitHub with: - - Release title (taken from changelog) - - Changelog - -### Announcements -- Where to announce new Pico release? +Inside the root Pico folder, all __themes__ reside in the `themes` directory, and all __plugins__ in the `plugins` directory. --- diff --git a/_plugin-dev/core.md b/_plugin-dev/core.md index a90b4c4..df33a3d 100644 --- a/_plugin-dev/core.md +++ b/_plugin-dev/core.md @@ -10,6 +10,7 @@ nav: 2 It's generally not a good idea to make modifications to the core of Pico. If you are looking to add or change functionality, can it be accomplished with a plugin? -If not, and you are interested in helping to develop the Pico core, [fork us on GitHub](https://github.com/picocms/Pico)! + +If not, and you want to contribute to Picos core please refer to our [CONTRIBUTING.md](https://github.com/picocms/Pico/blob/master/CONTRIBUTING.md) on GitHub. --- diff --git a/_plugin-dev/plugins.md b/_plugin-dev/plugins.md index a479c1f..378829a 100644 --- a/_plugin-dev/plugins.md +++ b/_plugin-dev/plugins.md @@ -10,11 +10,11 @@ nav: 3 # Plugins At the heart of customizing Pico is a plugin. You can 'hook-in' to the Pico engine at many different times during the rendering of your site and its content. -You will find a full example template in `plugins/DummyPlugin.php` to get you +You will find a full example template in [plugins/DummyPlugin.php]({{ site.base_url }}/phpDoc/master/classes/DummyPlugin.html) to get you started on building some great stuff. Otherwise, keep reading to learn how to create your first plugin! -Officially tested plugins can be found at [http://picocms.org/plugins](http://picocms.org/plugins), +Officially tested plugins can be found at [http://picocms.org/plugins]({{ site.base_url }}/plugins.html), but there are many awesome third-party plugins out there! A good start point for discovery is our [Wiki](#plugin-wiki). @@ -24,8 +24,8 @@ for discovery is our [Wiki](#plugin-wiki). The new event system supports plugin dependencies as well as some new events. You will be able to set an enabled/disabled state by default as well. If you have previously cerated a plugin for Pico, it is *HIGHLY* recommended that you -update your class to extend from `AbstractPicoPlugin` and use the new events -to avoid activating the `PicoDeprecated` plugin. +update your class to extend from [AbstractPicoPlugin]({{ site.base_url }}/phpDoc/master/classes/AbstractPicoPlugin.html) and use the new events +to avoid activating the [PicoDeprecated](https://github.com/picocms/Pico/blob/master/plugins/00-PicoDeprecated.php) plugin. |---------------------|-----------------------------------------------------------| | Event | ... triggers the deprecated event | @@ -54,12 +54,12 @@ to avoid activating the `PicoDeprecated` plugin. # Your First Plugin ## 1. To get started, navigate to your `plugins` directory -![Step1](style/images/docs/pico_plugins.jpg) +![Step1]({{ site.base_url }}/style/images/docs/pico_plugins.jpg) --- ## 2. Create a new folder and name it your desired name using CammelCase -![Step2](style/images/docs/pico_plugins_myplugin.jpg) +![Step2]({{ site.base_url }}/style/images/docs/pico_plugins_myplugin.jpg) > *Note:* It's not necessary to create the folder, if you do not have assets to > include, you can simply skip this step and continue to Step 3 @@ -67,19 +67,19 @@ to avoid activating the `PicoDeprecated` plugin. --- ## 3. Next, you should copy `DummyPlugin.php` inside your newly created folder and give it the same name as you did the folder -![Step3](style/images/docs/pico_plugins_myplugin_php.jpg) +![Step3]({{ site.base_url }}/style/images/docs/pico_plugins_myplugin_php.jpg) --- ## 4. You will need to name the `class` the same as the `folder` and the `.php` file -![Step4](style/images/docs/pico_plugins_myplugin_php_class.jpg) +![Step4]({{ site.base_url }}/style/images/docs/pico_plugins_myplugin_php_class.jpg) --- ## 5. From here, you will be able to hook-in to Pico's processing Choose an event that makes sense for your situation. Do you need to load configuration values? -`onConfigLoaded`. You need to modify the content of the page before it is -rendered by markdown? `onPageRendering`. Etc... Plugin developers shouldn't +[onConfigLoaded]({{ site.base_url }}/phpDoc/master/classes/DummyPlugin.html#method_onConfigLoaded). You need to modify the content of the page before it is +rendered by markdown? [onPageRendering]({{ site.base_url }}/phpDoc/master/classes/DummyPlugin.html#method_onPageRendering). Etc... Plugin developers shouldn't manipulate data in "wrong" events, this could lead to unexpected behavior. > *Note:* Don't forget to set your plugins enabled/disabled state, either by default or