Welcome to Pico


Creating Content


When you install Pico, it comes with a content-sample folder. Inside this folder is a sample website that will display until you add your own content. You should create your own content folder in Pico's root directory and place your files there. No configuration is required, Pico will automatically use the content folder if it exists.

If you create a folder within the content folder (e.g. content/sub) and put an index.md inside it, you can access that folder at the URL http://example.com/?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 http://example.com/?sub/page). Below we've shown some examples of locations and their corresponding URLs:

Physical Location URL
content/index.md /
content/sub.md ?sub (not accessible, see below)
content/sub/index.md ?sub (same as above)
content/sub/page.md ?sub/page


As a common practice, we recommend you to separate your contents and assets (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 your assets there. You can then access them in your markdown using %base_url%/assets/ for example: ![Image Title](%base_url%/assets/image.png)

Text File Markup



Title: Welcome
Description: This description will go in the meta description tag
Author: Joe Bloggs
Date: 2013/01/01
Robots: noindex,nofollow
Template: index






  1. Put all your blog articles in a separate blog folder in your content directory. All these articles should have both a Date and Template meta header, the latter with e.g. blog-post as value (see Step 2).
  2. Create a new Twig template called blog-post.twig (this must match the Template meta header from Step 1) in your theme directory. This template probably isn't very different from your default index.twig, it specifies how your article pages will look like.
  3. Create a blog.md in your content folder and set its Template meta header to e.g. blog. Also create a blog.twig in your theme directory. This template will show a list of your articles, so you probably want to do something like this:
    {% for page in pages|sort_by("time")|reverse %}
        {% if page.id starts with "blog/" %}
            <div class="post">
        {% endif %}
    {% endfor %}
  4. Make sure to exclude blog articles from your page navigation. You can achieve this by adding {% if not (page.id starts with "blog/") %}...{% endif %} to the navigation loop ({% for page in pages %}...{% endfor %}) in your theme's index.twig.





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 rendering. You can select your theme by setting the $config['theme'] option in config/config.php to the name of your theme folder.

All themes must include an index.twig (or index.html) 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 (e.g. {{ base_url }}) don't have a trailing slash.

Pages can be used like the following:

<ul class="nav">
    {% for page in pages %}
    {% endfor %}

Additional to Twigs extensive list of filters, functions and tags, Pico also provides some useful additional filters to make theming easier. You can parse any Markdown string to HTML using the markdown filter. Arrays can be sorted by one of its keys or a arbitrary deep sub-key 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 page.meta.nav). You can return all values of a given key or key path of an array using the map filter (e.g. {{ pages|map("title") }} returns all page titles).

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.

You don't have to create your own theme if Pico's default theme isn't sufficient 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 and on our website.


Plugins for users


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. 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 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.

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/development/. If you've developed a plugin for Pico 0.9 or 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.


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 override a setting, copy config/config.php.template to config/config.php, uncomment the setting and set your custom value.

URL Rewriting

Pico's default URLs (e.g. http://jasonsilkey.com/?sub/page) already are very user-friendly. Additionally, Pico offers you a URL rewrite feature to make URLs even more user-friendly (e.g. http://jasonsilkey.com/sub/page).

If you're using the Apache web server, URL rewriting probably already is enabled - try it yourself, click on the second URL. If you get an error message from your web server, please make sure to enable the mod_rewrite module. Assuming the second URL works, but Pico still shows no rewritten URLs, force URL rewriting by setting $config['rewrite_url'] = true; in your config/config.php.

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, 5 and 7) to match your installation directory. Additionally, you'll need to enable URL rewriting by setting $config['rewrite_url'] = true; in your config/config.php. 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.

location ~ /pico/(\.htaccess|\.git|config|content|content-sample|lib|vendor|CHANGELOG\.md|composer\.(json|lock)) {
    return 404;

location ~ ^/pico(.*) {
    index index.php;
    try_files $uri $uri/ /pico/index.php?$1&$args;

