2015-08-28 16:34:14 +00:00
|
|
|
---
|
2012-04-04 13:45:09 +00:00
|
|
|
Title: Welcome
|
2015-08-28 16:34:14 +00:00
|
|
|
Description: Pico is a stupidly simple, blazing fast, flat file CMS.
|
|
|
|
---
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2013-05-01 13:34:24 +00:00
|
|
|
## Welcome to Pico
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
Congratulations, you have successfully installed [Pico][] %version%.
|
|
|
|
%meta.description% <!-- replaced by the above Description header -->
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-10-09 22:08:38 +00:00
|
|
|
## Creating Content
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-12-07 00:28:37 +00:00
|
|
|
Pico is a flat file CMS. This means there is no administration backend or
|
2015-12-21 02:24:32 +00:00
|
|
|
database to deal with. You simply create `.md` files in the `content` folder
|
2015-12-21 11:50:31 +00:00
|
|
|
and those files become your pages. For example, this file is called `index.md`
|
|
|
|
and is shown as the main landing page.
|
2015-12-07 00:28:37 +00:00
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
When you install Pico, it comes with some sample contents 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`. Just check out [Pico's sample contents][SampleContents] for an
|
|
|
|
example!
|
2018-01-28 12:20:13 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
`%base_url%?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 `%base_url%?sub/page`).
|
|
|
|
Below we've shown some examples of locations and their corresponding URLs:
|
2015-08-28 16:34:14 +00:00
|
|
|
|
|
|
|
<table style="width: 100%; max-width: 40em;">
|
|
|
|
<thead>
|
|
|
|
<tr>
|
|
|
|
<th style="width: 50%;">Physical Location</th>
|
|
|
|
<th style="width: 50%;">URL</th>
|
|
|
|
</tr>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<tr>
|
2015-12-06 19:35:39 +00:00
|
|
|
<td>content/index.md</td>
|
2015-08-28 16:34:14 +00:00
|
|
|
<td><a href="%base_url%">/</a></td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2015-12-06 19:35:39 +00:00
|
|
|
<td>content/sub.md</td>
|
2015-08-28 16:34:14 +00:00
|
|
|
<td><del>?sub</del> (not accessible, see below)</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2015-12-06 19:35:39 +00:00
|
|
|
<td>content/sub/index.md</td>
|
2015-08-28 16:34:14 +00:00
|
|
|
<td><a href="%base_url%?sub">?sub</a> (same as above)</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2015-12-06 19:35:39 +00:00
|
|
|
<td>content/sub/page.md</td>
|
2015-08-28 16:34:14 +00:00
|
|
|
<td><a href="%base_url%?sub/page">?sub/page</a></td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2015-12-06 19:35:39 +00:00
|
|
|
<td>content/a/very/long/url.md</td>
|
2015-12-07 00:28:37 +00:00
|
|
|
<td>
|
|
|
|
<a href="%base_url%?a/very/long/url">?a/very/long/url</a>
|
|
|
|
(doesn't exist)
|
|
|
|
</td>
|
2015-08-28 16:34:14 +00:00
|
|
|
</tr>
|
|
|
|
</tbody>
|
2012-04-04 13:45:09 +00:00
|
|
|
</table>
|
|
|
|
|
2015-12-07 00:28:37 +00:00
|
|
|
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`.
|
2015-11-02 19:00:31 +00:00
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
Pico strictly separates contents of your website (the Markdown files in your
|
|
|
|
`content` directory) and how these contents should be displayed (the Twig
|
|
|
|
templates in your `themes` directory). However, not every file in your `content`
|
|
|
|
directory might actually be a distinct page. For example, some themes (including
|
|
|
|
Pico's default theme) use some special "hidden" file to manage meta data (like
|
|
|
|
`_meta.md` in Pico's sample contents). Some other themes use a `_footer.md` to
|
|
|
|
represent the contents of the website's footer. The common point is the `_`: all
|
|
|
|
files and directories prefixed by a `_` in your `content` directory are hidden.
|
|
|
|
These pages can't be accessed from a web browser, Pico will show a 404 error
|
|
|
|
page instead.
|
|
|
|
|
2015-11-13 23:26:26 +00:00
|
|
|
As a common practice, we recommend you to separate your contents and assets
|
2015-12-07 00:28:37 +00:00
|
|
|
(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
|
2018-01-28 12:20:13 +00:00
|
|
|
your assets there. You can then access them in your Markdown using
|
2015-12-07 00:28:37 +00:00
|
|
|
<code>%base_url%/assets/</code> for example:
|
|
|
|
<code>!\[Image Title\](%base_url%/assets/image.png)</code>
|
2015-11-13 23:26:26 +00:00
|
|
|
|
2013-05-01 13:34:24 +00:00
|
|
|
### Text File Markup
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2016-02-04 13:23:16 +00:00
|
|
|
Text files are marked up using [Markdown][] and [Markdown Extra][MarkdownExtra].
|
|
|
|
They can also contain regular HTML.
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-11-29 19:26:43 +00:00
|
|
|
At the top of text files you can place a block comment and specify certain meta
|
|
|
|
attributes of the page using [YAML][] (the "YAML header"). For example:
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-08-28 16:34:14 +00:00
|
|
|
---
|
|
|
|
Title: Welcome
|
|
|
|
Description: This description will go in the meta description tag
|
|
|
|
Author: Joe Bloggs
|
2018-01-28 12:20:13 +00:00
|
|
|
Date: 2001-04-25
|
2015-08-28 16:34:14 +00:00
|
|
|
Robots: noindex,nofollow
|
2015-10-09 15:49:07 +00:00
|
|
|
Template: index
|
2015-08-28 16:34:14 +00:00
|
|
|
---
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2018-01-28 12:20:13 +00:00
|
|
|
These values will be contained in the `{{ meta }}` 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`).
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2018-12-03 10:50:28 +00:00
|
|
|
In an attempt to separate contents and styling, we recommend you to not use
|
|
|
|
inline CSS in your Markdown files. You should rather add appropriate CSS
|
|
|
|
classes to your theme. For example, you might want to add some CSS classes to
|
|
|
|
your theme to rule how much of the available space a image should use (e.g.
|
|
|
|
`img.small { width: 80%; }`). You can then use these CSS classes in your
|
|
|
|
Markdown files, for example:
|
|
|
|
<code>!\[Image Title\](%base_url%/assets/image.png) {.small}</code>
|
|
|
|
|
2012-04-04 13:45:09 +00:00
|
|
|
There are also certain variables that you can use in your text files:
|
|
|
|
|
2015-08-28 16:34:14 +00:00
|
|
|
* <code>%site_title%</code> - The title of your Pico site
|
|
|
|
* <code>%base_url%</code> - The URL to your Pico site; internal links
|
|
|
|
can be specified using <code>%base_url%?sub/page</code>
|
|
|
|
* <code>%theme_url%</code> - The URL to the currently used theme
|
2018-07-29 10:46:37 +00:00
|
|
|
* <code>%version%</code> - Pico's current version string (e.g. `2.0.0`)
|
2015-12-07 00:28:37 +00:00
|
|
|
* <code>%meta.*%</code> - Access any meta variable of the current
|
2015-12-21 02:24:32 +00:00
|
|
|
page, e.g. <code>%meta.author%</code> is replaced with `Joe Bloggs`
|
2015-10-08 19:01:30 +00:00
|
|
|
|
|
|
|
### Blogging
|
|
|
|
|
2015-10-09 15:49:07 +00:00
|
|
|
Pico is not blogging software - but makes it very easy for you to use it as a
|
2015-10-09 18:51:07 +00:00
|
|
|
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.
|
2015-10-08 19:01:30 +00:00
|
|
|
|
|
|
|
If you want to use Pico as a blogging software, you probably want to do
|
|
|
|
something like the following:
|
2018-01-28 12:20:13 +00:00
|
|
|
|
2015-10-08 19:01:30 +00:00
|
|
|
1. Put all your blog articles in a separate `blog` folder in your `content`
|
2018-12-16 12:46:24 +00:00
|
|
|
directory. All these articles should have a `Date` meta header.
|
|
|
|
2. Create a `blog.md` or `blog/index.md` in your `content` directory. Add
|
|
|
|
`Template: blog-index` to the YAML header of this page. It will later show a
|
|
|
|
list of all your blog articles (see step 3).
|
|
|
|
3. Create the new Twig template `blog-index.twig` (the file name must match the
|
|
|
|
`Template` meta header from Step 2) in your theme directory. This template
|
|
|
|
probably isn't very different from your default `index.twig` (i.e. copy
|
|
|
|
`index.twig`), it will create a list of all your blog articles. Add the
|
|
|
|
following Twig snippet to `blog-index.twig` near `{{ content }}`:
|
2015-10-08 19:01:30 +00:00
|
|
|
```
|
2015-11-29 21:28:18 +00:00
|
|
|
{% for page in pages|sort_by("time")|reverse %}
|
2018-01-28 12:20:13 +00:00
|
|
|
{% if page.id starts with "blog/" and not page.hidden %}
|
2015-10-08 19:01:30 +00:00
|
|
|
<div class="post">
|
|
|
|
<h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
|
|
|
|
<p class="date">{{ page.date_formatted }}</p>
|
|
|
|
<p class="excerpt">{{ page.description }}</p>
|
|
|
|
</div>
|
|
|
|
{% endif %}
|
|
|
|
{% endfor %}
|
|
|
|
```
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-10-09 22:08:38 +00:00
|
|
|
## Customization
|
|
|
|
|
|
|
|
Pico is highly customizable in two different ways: On the one hand you can
|
2015-11-04 18:43:06 +00:00
|
|
|
change Pico's appearance by using themes, on the other hand you can add new
|
|
|
|
functionality by using plugins. Doing the former includes changing Pico's HTML,
|
2015-10-09 22:08:38 +00:00
|
|
|
CSS and JavaScript, the latter mostly consists of PHP programming.
|
|
|
|
|
|
|
|
This is all Greek to you? Don't worry, you don't have to spend time on these
|
|
|
|
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.
|
|
|
|
|
2013-05-01 13:34:24 +00:00
|
|
|
### Themes
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-08-28 16:34:14 +00:00
|
|
|
You can create themes for your Pico installation in the `themes` folder. Check
|
2015-10-08 19:01:30 +00:00
|
|
|
out the default theme for an example. Pico uses [Twig][] for template
|
2017-02-05 23:01:25 +00:00
|
|
|
rendering. You can select your theme by setting the `theme` option in
|
|
|
|
`config/config.yml` to the name of your theme folder.
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2018-01-28 12:20:13 +00:00
|
|
|
All themes must include an `index.twig` file to define the HTML structure of
|
|
|
|
the theme. Below are the Twig variables that are available to use in your
|
|
|
|
theme. Please note that paths (e.g. `{{ base_dir }}`) and URLs
|
2015-10-08 19:01:30 +00:00
|
|
|
(e.g. `{{ base_url }}`) don't have a trailing slash.
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
* `{{ site_title }}` - Shortcut to the site title (see `config/config.yml`)
|
2017-02-05 23:01:25 +00:00
|
|
|
* `{{ config }}` - Contains the values you set in `config/config.yml`
|
2015-10-08 19:01:30 +00:00
|
|
|
(e.g. `{{ config.theme }}` becomes `default`)
|
2012-04-04 13:45:09 +00:00
|
|
|
* `{{ base_dir }}` - The path to your Pico root directory
|
2018-01-28 12:20:13 +00:00
|
|
|
* `{{ base_url }}` - The URL to your Pico site; use Twig's `link` filter to
|
2015-10-09 12:27:49 +00:00
|
|
|
specify internal links (e.g. `{{ "sub/page"|link }}`),
|
|
|
|
this guarantees that your link works whether URL rewriting
|
|
|
|
is enabled or not
|
2015-10-08 19:01:30 +00:00
|
|
|
* `{{ theme_dir }}` - The path to the currently active theme
|
|
|
|
* `{{ theme_url }}` - The URL to the currently active theme
|
2018-07-29 10:46:37 +00:00
|
|
|
* `{{ version }}` - Pico's current version string (e.g. `2.0.0`)
|
2018-01-28 12:20:13 +00:00
|
|
|
* `{{ meta }}` - Contains the meta values of the current page
|
2015-08-28 16:34:14 +00:00
|
|
|
* `{{ meta.title }}`
|
|
|
|
* `{{ meta.description }}`
|
|
|
|
* `{{ meta.author }}`
|
|
|
|
* `{{ meta.date }}`
|
|
|
|
* `{{ meta.date_formatted }}`
|
2015-10-08 19:01:30 +00:00
|
|
|
* `{{ meta.time }}`
|
2015-08-28 16:34:14 +00:00
|
|
|
* `{{ meta.robots }}`
|
2015-10-08 19:01:30 +00:00
|
|
|
* ...
|
2018-01-28 12:20:13 +00:00
|
|
|
* `{{ content }}` - The content of the current page after it has been processed
|
|
|
|
through Markdown
|
2015-08-28 16:34:14 +00:00
|
|
|
* `{{ pages }}` - A collection of all the content pages in your site
|
2015-11-06 00:08:31 +00:00
|
|
|
* `{{ page.id }}` - The relative path to the content file (unique ID)
|
2015-10-28 23:54:01 +00:00
|
|
|
* `{{ page.url }}` - The URL to the page
|
|
|
|
* `{{ page.title }}` - The title of the page (YAML header)
|
|
|
|
* `{{ page.description }}` - The description of the page (YAML header)
|
|
|
|
* `{{ page.author }}` - The author of the page (YAML header)
|
2018-01-28 12:20:13 +00:00
|
|
|
* `{{ page.time }}` - The [Unix timestamp][UnixTimestamp] derived from
|
|
|
|
the `Date` header
|
2015-10-28 23:54:01 +00:00
|
|
|
* `{{ page.date }}` - The date of the page (YAML header)
|
2018-01-28 12:20:13 +00:00
|
|
|
* `{{ page.date_formatted }}` - The formatted date of the page as specified
|
|
|
|
by the `date_format` parameter in your
|
|
|
|
`config/config.yml`
|
2015-11-06 00:08:31 +00:00
|
|
|
* `{{ page.raw_content }}` - The raw, not yet parsed contents of the page;
|
2018-01-28 12:20:13 +00:00
|
|
|
use Twig's `content` filter to get the parsed
|
2015-11-06 00:08:31 +00:00
|
|
|
contents of a page by passing its unique ID
|
|
|
|
(e.g. `{{ "sub/page"|content }}`)
|
2018-07-29 10:46:37 +00:00
|
|
|
* `{{ page.meta }}`- The meta values of the page (see `{{ meta }}` above)
|
|
|
|
* `{{ page.previous_page }}` - The data of the respective previous page
|
|
|
|
* `{{ page.next_page }}` - The data of the respective next page
|
|
|
|
* `{{ page.tree_node }}` - The page's node in Pico's page tree
|
2015-08-28 16:34:14 +00:00
|
|
|
* `{{ prev_page }}` - The data of the previous page (relative to `current_page`)
|
2018-07-29 10:46:37 +00:00
|
|
|
* `{{ current_page }}` - The data of the current page (see `{{ pages }}` above)
|
2015-08-28 16:34:14 +00:00
|
|
|
* `{{ next_page }}` - The data of the next page (relative to `current_page`)
|
2013-05-03 14:45:42 +00:00
|
|
|
|
2015-10-08 19:01:30 +00:00
|
|
|
Pages can be used like the following:
|
2012-04-04 13:45:09 +00:00
|
|
|
|
2015-10-08 19:01:30 +00:00
|
|
|
<ul class="nav">
|
2018-01-28 12:20:13 +00:00
|
|
|
{% for page in pages if not page.hidden %}
|
2015-10-08 19:01:30 +00:00
|
|
|
<li><a href="{{ page.url }}">{{ page.title }}</a></li>
|
|
|
|
{% endfor %}
|
|
|
|
</ul>
|
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
Besides using the `{{ pages }}` list, you can also access pages using Pico's
|
|
|
|
page tree. The page tree allows you to iterate through Pico's pages using a tree
|
|
|
|
structure, so you can e.g. iterate just a page's direct children. It allows you
|
|
|
|
to build recursive menus (like dropdowns) and to filter pages more easily. Just
|
|
|
|
head over to Pico's [page tree documentation][FeaturesPageTree] for details.
|
|
|
|
|
2018-12-03 10:50:28 +00:00
|
|
|
To call assets from your theme, use `{{ theme_url }}`. For instance, to include
|
|
|
|
the CSS file `themes/my_theme/example.css`, add
|
|
|
|
`<link rel="stylesheet" href="{{ theme_url }}/example.css" type="text/css" />`
|
|
|
|
to your `index.twig`. This works for arbitrary files in your theme's folder,
|
|
|
|
including images and JavaScript files.
|
|
|
|
|
2015-11-13 16:08:12 +00:00
|
|
|
Additional to Twigs extensive list of filters, functions and tags, Pico also
|
2018-01-28 12:20:13 +00:00
|
|
|
provides some useful additional filters to make theming easier.
|
|
|
|
|
|
|
|
* Pass the unique ID of a page to the `link` filter to return the page's URL
|
2018-02-03 17:28:37 +00:00
|
|
|
(e.g. `{{ "sub/page"|link }}` gets `%base_url%?sub/page`).
|
2018-01-28 12:20:13 +00:00
|
|
|
* To get the parsed contents of a page, pass its unique ID to the `content`
|
|
|
|
filter (e.g. `{{ "sub/page"|content }}`).
|
|
|
|
* You can parse any Markdown string using the `markdown` filter (e.g. you can
|
|
|
|
use Markdown in the `description` meta variable and later parse it in your
|
2018-07-29 10:46:37 +00:00
|
|
|
theme using `{{ meta.description|markdown }}`). You can pass meta data as
|
|
|
|
parameter to replace <code>%meta.*%</code> placeholders (e.g.
|
|
|
|
`{{ "Written *by %meta.author%*"|markdown(meta) }}` yields "Written by
|
|
|
|
*John Doe*").
|
2018-01-28 12:20:13 +00:00
|
|
|
* Arrays can be sorted by one of its keys using the `sort_by` filter
|
|
|
|
(e.g. `{% for page in pages|sort_by([ 'meta', 'nav' ]) %}...{% endfor %}`
|
|
|
|
iterates through all pages, ordered by the `nav` meta header; please note the
|
|
|
|
`[ 'meta', 'nav' ]` part of the example, it instructs Pico to sort by
|
2018-07-29 10:46:37 +00:00
|
|
|
`page.meta.nav`). Items which couldn't be sorted are moved to the bottom of
|
|
|
|
the array; you can specify `bottom` (move items to bottom; default), `top`
|
|
|
|
(move items to top), `keep` (keep original order) or `remove` (remove items)
|
|
|
|
as second parameter to change this behavior.
|
2018-01-28 12:20:13 +00:00
|
|
|
* You can return all values of a given array key using the `map` filter
|
|
|
|
(e.g. `{{ pages|map("title") }}` returns all page titles).
|
2018-07-29 10:46:37 +00:00
|
|
|
* Use the `url_param` and `form_param` Twig functions to access HTTP GET (i.e.
|
|
|
|
a URL's query string like `?some-variable=my-value`) and HTTP POST (i.e. data
|
|
|
|
of a submitted form) parameters. This allows you to implement things like
|
|
|
|
pagination, tags and categories, dynamic pages, and even more - with pure
|
|
|
|
Twig! Simply head over to our [introductory page for accessing HTTP
|
|
|
|
parameters][FeaturesHttpParams] for details.
|
2015-11-13 16:08:12 +00:00
|
|
|
|
2015-11-03 15:35:27 +00:00
|
|
|
You can use different templates for different content files by specifying the
|
2018-01-28 12:20:13 +00:00
|
|
|
`Template` meta header. Simply add e.g. `Template: blog` to the YAML header of
|
|
|
|
a content file and Pico will use the `blog.twig` template in your theme folder
|
|
|
|
to display the page.
|
2015-10-08 19:01:30 +00:00
|
|
|
|
2018-01-28 12:20:13 +00:00
|
|
|
Pico's default theme isn't really intended to be used for a productive website,
|
|
|
|
it's rather a starting point for creating your own theme. If the default theme
|
|
|
|
isn't sufficient for you, and you don't want to create your own theme, 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][WikiThemes] and on
|
|
|
|
[our website][OfficialThemes].
|
2013-05-01 13:34:24 +00:00
|
|
|
|
2013-09-04 11:10:26 +00:00
|
|
|
### Plugins
|
|
|
|
|
2015-10-08 19:01:30 +00:00
|
|
|
#### Plugins for users
|
|
|
|
|
2016-11-02 02:12:02 +00:00
|
|
|
Officially tested plugins can be found at http://picocms.org/plugins/, but
|
|
|
|
there are many awesome third-party plugins out there! A good start point for
|
|
|
|
discovery is [our Wiki][WikiPlugins].
|
2015-10-08 19:01:30 +00:00
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
Pico makes it very easy for you to add new features to your website using
|
|
|
|
plugins. Just like Pico, you can install plugins either using [Composer][]
|
|
|
|
(e.g. `composer require phrozenbyte/pico-file-prefixes`), or manually by
|
|
|
|
uploading the plugin's file (just for small plugins consisting of a single file,
|
|
|
|
e.g. `PicoFilePrefixes.php`) or directory (e.g. `PicoFilePrefixes`) to your
|
|
|
|
`plugins` directory. We always recommend you to use Composer whenever possible,
|
|
|
|
because it makes updating both Pico and your plugins way easier. Anyway,
|
|
|
|
depending on the plugin you want to install, you may have to go through some
|
|
|
|
more steps (e.g. specifying config variables) to make the plugin work. Thus you
|
|
|
|
should always check out the plugin's docs or `README.md` file to learn the
|
|
|
|
necessary steps.
|
2015-10-08 19:01:30 +00:00
|
|
|
|
2018-01-28 12:20:13 +00:00
|
|
|
Plugins which were written to work with Pico 1.0 and later can be enabled and
|
|
|
|
disabled through your `config/config.yml`. If you want to e.g. disable the
|
|
|
|
`PicoDeprecated` plugin, add the following line to your `config/config.yml`:
|
|
|
|
`PicoDeprecated.enabled: false`. To force the plugin to be enabled, replace
|
|
|
|
`false` by `true`.
|
2015-10-08 19:01:30 +00:00
|
|
|
|
|
|
|
#### Plugins for developers
|
|
|
|
|
|
|
|
You're a plugin developer? We love you guys! You can find tons of information
|
2015-12-20 18:44:59 +00:00
|
|
|
about how to develop plugins at http://picocms.org/development/. If you've
|
2018-01-28 12:20:13 +00:00
|
|
|
developed a plugin before and want to upgrade it to Pico 2.0, refer to the
|
2015-10-28 23:57:54 +00:00
|
|
|
[upgrade section of the docs][PluginUpgrade].
|
2015-10-08 19:01:30 +00:00
|
|
|
|
2015-10-09 22:11:56 +00:00
|
|
|
## Config
|
|
|
|
|
2018-07-01 15:16:29 +00:00
|
|
|
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
|
2018-07-29 10:46:37 +00:00
|
|
|
order is crucial: Config values which have been set already, cannot be
|
2018-07-01 15:16:29 +00:00
|
|
|
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.
|
2015-10-09 22:11:56 +00:00
|
|
|
|
2015-10-08 19:01:30 +00:00
|
|
|
### URL Rewriting
|
|
|
|
|
2015-11-04 18:43:06 +00:00
|
|
|
Pico's default URLs (e.g. %base_url%/?sub/page) already are very user-friendly.
|
2015-11-06 16:50:22 +00:00
|
|
|
Additionally, Pico offers you a URL rewrite feature to make URLs even more
|
2018-07-01 15:16:29 +00:00
|
|
|
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.
|
2015-10-08 19:01:30 +00:00
|
|
|
|
2018-02-03 17:28:37 +00:00
|
|
|
#### Apache
|
|
|
|
|
2015-10-08 19:01:30 +00:00
|
|
|
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
|
2018-07-01 15:16:29 +00:00
|
|
|
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).
|
2015-10-08 19:01:30 +00:00
|
|
|
|
2018-02-03 17:28:37 +00:00
|
|
|
#### Nginx
|
|
|
|
|
2018-07-01 15:16:29 +00:00
|
|
|
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].
|
2016-05-06 21:17:17 +00:00
|
|
|
|
|
|
|
```
|
2018-01-27 20:08:56 +00:00
|
|
|
location ~ ^/pico/((config|content|vendor|composer\.(json|lock|phar))(/|$)|(.+/)?\.(?!well-known(/|$))) {
|
2018-07-29 10:46:37 +00:00
|
|
|
try_files /pico/index.php$is_args$args =404;
|
2016-05-06 21:17:17 +00:00
|
|
|
}
|
|
|
|
|
2016-06-18 18:23:23 +00:00
|
|
|
location /pico/ {
|
2016-05-06 21:17:17 +00:00
|
|
|
index index.php;
|
2016-06-18 18:23:23 +00:00
|
|
|
try_files $uri $uri/ /pico/index.php$is_args$args;
|
2016-05-06 21:17:17 +00:00
|
|
|
}
|
|
|
|
```
|
2013-09-04 11:10:26 +00:00
|
|
|
|
2018-02-03 17:28:37 +00:00
|
|
|
#### Lighttpd
|
|
|
|
|
2018-07-01 15:16:29 +00:00
|
|
|
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.
|
2018-02-03 17:28:37 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
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"
|
|
|
|
)
|
|
|
|
```
|
|
|
|
|
2015-10-09 22:08:38 +00:00
|
|
|
## Documentation
|
2013-09-04 11:10:26 +00:00
|
|
|
|
2015-11-02 23:41:10 +00:00
|
|
|
For more help have a look at the Pico documentation at http://picocms.org/docs.
|
2015-08-28 16:34:14 +00:00
|
|
|
|
2018-07-29 10:46:37 +00:00
|
|
|
[Pico]: http://picocms.org/
|
|
|
|
[SampleContents]: https://github.com/picocms/Pico/tree/master/content-sample
|
2015-08-28 16:34:14 +00:00
|
|
|
[Markdown]: http://daringfireball.net/projects/markdown/syntax
|
2016-02-04 13:23:16 +00:00
|
|
|
[MarkdownExtra]: https://michelf.ca/projects/php-markdown/extra/
|
2015-11-29 19:26:43 +00:00
|
|
|
[YAML]: https://en.wikipedia.org/wiki/YAML
|
2015-11-02 23:41:10 +00:00
|
|
|
[Twig]: http://twig.sensiolabs.org/documentation
|
2018-01-28 12:20:13 +00:00
|
|
|
[UnixTimestamp]: https://en.wikipedia.org/wiki/Unix_timestamp
|
2018-07-29 10:46:37 +00:00
|
|
|
[Composer]: https://getcomposer.org/
|
|
|
|
[FeaturesHttpParams]: http://picocms.org/in-depth/features/http-params/
|
|
|
|
[FeaturesPageTree]: http://picocms.org/in-depth/features/page-tree/
|
2015-11-02 23:41:10 +00:00
|
|
|
[WikiThemes]: https://github.com/picocms/Pico/wiki/Pico-Themes
|
|
|
|
[WikiPlugins]: https://github.com/picocms/Pico/wiki/Pico-Plugins
|
2016-11-02 02:12:02 +00:00
|
|
|
[OfficialThemes]: http://picocms.org/themes/
|
2015-12-20 18:44:59 +00:00
|
|
|
[PluginUpgrade]: http://picocms.org/development/#upgrade
|
2015-11-04 18:43:06 +00:00
|
|
|
[ModRewrite]: https://httpd.apache.org/docs/current/mod/mod_rewrite.html
|
2018-07-01 15:16:29 +00:00
|
|
|
[AllowOverride]: https://httpd.apache.org/docs/current/mod/core.html#allowoverride
|
2016-05-06 21:17:17 +00:00
|
|
|
[NginxConfig]: http://picocms.org/in-depth/nginx/
|