0ct0pu5/Pico
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

misc. formatting changes

Browse source
This commit is contained in:
theshka 2015-10-29 11:25:10 -06:00
parent 61d9acde85
commit 75c66657d9
8 changed files with 126 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
_docs/config.md
View file

@ -14,6 +14,8 @@ the available settings and their defaults see `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.
---
### URL Rewriting
Picos default URLs (e.g. http://example.com/pico/?sub/page) already are very
@ -35,3 +37,5 @@ setting `$config['rewrite_url'] = true;` in your `config/config.php`.
index index.php;
try_files $uri $uri/ /pico/?$uri&$args;
}
---

6
_docs/creating-content.md
View file

@ -57,6 +57,8 @@ If a file cannot be found, the file `content-sample/404.md` will be shown. You
can add `404.md` files to any directory, so if you want to use a special error
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.
@ -85,6 +87,8 @@ There are also certain variables that you can use in your text files:
* <code>&#37;meta.*&#37;</code> - Access any meta variable of the current page,
e.g. <code>&#37;meta.author&#37;</code> is replaced with `Joe Bloggs`
---
### Blogging
Pico is not blogging software - but makes it very easy for you to use it as a
@ -139,3 +143,5 @@ something like the following:
</ol>
[Markdown]: http://daringfireball.net/projects/markdown/syntax
---

6
_docs/customization.md
View file

@ -19,6 +19,8 @@ techie talk - it's very easy to use one of the great themes or plugins others
developed and released to the public. Please refer to the next sections for
details.
---
### Themes
You can create themes for your Pico installation in the `themes` folder. Check
@ -87,6 +89,8 @@ for you, you can use one of the great themes third-party developers and
designers created in the past. As with plugins, you can find themes in
[our Wiki](https://github.com/picocms/Pico/wiki/Pico-Themes).
---
### Plugins
#### Plugins for users
@ -116,3 +120,5 @@ 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
---

6
_docs/install.md
View file

@ -31,7 +31,9 @@ Download [composer][] and run it with the `install` option:
<pre><code>$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar install</code></pre>
Pico is available on [Packagist.org](http://packagist.org/) and may be included in other projects via `composer require picocms/pico`
Pico is available on [Packagist.org](http://packagist.org/packages/picocms/pico) and may be included in other projects via `composer require picocms/pico`
---
## Run
@ -54,3 +56,5 @@ Access Pico from <http://localhost:8080>.
[LatestRelease]: https://github.com/picocms/Pico/releases/latest
[composer]: https://getcomposer.org/
[PHPServer]: http://php.net/manual/en/features.commandline.webserver.php
---

30
_docs/upgrade.md
View file

@ -15,41 +15,59 @@ nav: 5
Detailed below is some of the most important changes to note when upgrading Pico from a `0.x` release to the new `Pico 1.0.0-beta.1`
---
### 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).
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.
---
### 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()`
---
### 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.
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`.
>Note: 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](/plugin-dev.html#migrating-from-0x---10) section.
__That's all fine, but what do I need to do to upgrade?__
>Users, please refer to the websites of the plugins you're using to get updates for them.
---
### "That's all fine, but what do I need to do to upgrade?"
---
### Tutorial
We worked hard to make the upgrade process to `Pico 1.0.0` as easy as possible - and we think we made the grade!
Usually you don't have to consider anything special, nevertheless you should always make sure you __create a backup of your Pico installation before upgrading__.
---
#### 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)
---
#### 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)
>Please refer to the websites of the plugins you're using to get updates for them.
---
#### 3. Move your `config.php` to the new `config/` directory.
![Step 3](style/images/docs/pico_upgrade_move_config.jpg)
---
#### 4. URL Rewriting became optional in `Pico 1.0.0` If you don't use the `.htaccess` file provided by Pico, you must update your rewriting rules to let the webserver rewrite internal links (e.g. `index.php?sub/page`) correctly. You need not update your markdown files or custom Twig templates if you keep URL rewriting enabled. Otherwise you have to change all internal links in markdown files (e.g. `%base_url%?sub/page`) and your custom Twig templates (e.g. (e.g. `{{ "sub/page"|link }}`)).
Further reading:
@ -57,7 +75,13 @@ Further reading:
- MOD_REWRITE [http://httpd.apache.org/docs/current/mod/mod_rewrite.html](http://httpd.apache.org/docs/current/mod/mod_rewrite.html)
- QUERY_STRING [https://en.wikipedia.org/wiki/Query_string](https://en.wikipedia.org/wiki/Query_string)
---
#### 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
---

68
_plugin-dev/basics.md
View file

@ -10,3 +10,71 @@ 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?
---

2
_plugin-dev/core.md
View file

@ -11,3 +11,5 @@ 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)!
---

12
_plugin-dev/plugins.md
View file

@ -2,12 +2,12 @@
toc:
plugins:
_title: Plugins
migrating-from-0x---10: Migrating 0.X -> 1.0
migrating-from-0x-to-10: Migrating 0.X -> 1.0
your-first-plugin: Your First Plugin
nav: 3
---
#Plugins
# 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
@ -18,7 +18,9 @@ Officially tested plugins can be found at [http://picocms.org/plugins](http://pi
but there are many awesome third-party plugins out there! A good start point
for discovery is our [Wiki](#plugin-wiki).
#Migrating from 0.X -> 1.0
---
# Migrating from 0.X to 1.0
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
@ -47,7 +49,9 @@ to avoid activating the `PicoDeprecated` plugin.
| onPageRendered | after_render($output) |
|---------------------|-----------------------------------------------------------|
#Your First Plugin
---
# Your First Plugin
## 1. To get started, navigate to your `plugins` directory
![Step1](style/images/docs/pico_plugins.jpg)