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

Iterate through docs collection in docs.html

Browse source
This commit is contained in:
Daniel Rudolf 2015-10-10 00:41:55 +02:00
parent 2facc05b60
commit b628194c80
1 changed files with 5 additions and 276 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

281
docs.html
View file

@ -8,289 +8,18 @@ nav: 2
<div class="inner">
<h1 class="aligncenter">Pico Documentation</h1>
<p class="description aligncenter">
Pico is a flat file CMS, this means there is no administration backend and database to deal with.<br />
Pico is a flat file CMS, this means there is no administration backend or database to deal with.<br />
You simply create .md files in the "content" folder and that becomes a page.
</p><br />
<div class="one-fourth">
<ul>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#installation">Installation</a></li>
<li>
<a href="#creating-content">Creating Content</a>
<ul><li><a href="#text-file-markup">Text File Markup</a></li></ul>
</li>
<li>
<a href="#themeing">Themeing</a>
<ul><li><a href="#blogging">Blogging</a></li></ul>
</li>
<li>
<a href="#plugins">Plugins</a>
<ul><li><a href="#adding-custom-meta">Adding Custom Meta</a></li></ul>
</li>
<li><a href="#contribute">Contribute</a></li>
</ul>
<!-- ToDo -->
</div>
<div class="three-fourth last">
<h3 id="requirements">Requirements</h3>
<p>
To run Pico you simply need <strong>PHP 5.3+</strong> to be running on your server.
If you're running Apache you will require <code>mod_rewrite</code> to be enabled.
</p>
<hr>
<h3 id="installation">Installation</h3>
<ol>
<li>First <a href="download.html">download</a> and extract the latest version of Pico.</li>
<li>Upload the files to your server (via FTP or some other deployment).</li>
<li>Download <a href="https://getcomposer.org/">composer</a> and run it with install option.</li>
<pre><code>
$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar install
</code></pre>
<li>The easiest way to Pico is using <a href="http://php.net/manual/en/features.commandline.webserver.php">the built-in web server on PHP</a>.</li>
<pre><code>
$ php -S 0.0.0.0:8080 ./
</code></pre>
<li>Pico will be accessible from <a href="http://localhost:8080">http://localhost:8080</a>.</li>
<li>That's it. Tweak the <code>.htaccess</code> file if required.</li>
</ol><br />
<p>You can override the default Pico settings (and add your own custom settings) by editing <code>config/config.php</code> in the Pico directory. The <code>config/config.php.template</code> lists all of the settings and their defaults. To override a setting simply copy <code>config/config.php.template</code> to <code>config/config.php</code>, uncomment the setting and set your custom value.</p>
<hr>
<h3 id="creating-content">Creating Content</h3>
<p>
Pico is a flat file CMS, this means there is no administration backend and database to deal with.
You simply create <code>.md</code> files in the "content-sample" folder and that becomes a page.
</p>
<p>
If you created folder within the content-sample folder (e.g. <code>content-sample/sub</code>) and put an <code>index.md</code> inside it, you can access that folder at the URL
<code><a href="http://yoursite.com/sub">http://yoursite.com/sub</a></code>. If you want another page within the sub folder, simply create a text file with the corresponding name (e.g. <code>content-sample/sub/page.md</code>)
and will be able to access it from the URL <code><a href="http://yoursite.com/sub/page">http://yoursite.com/sub/page</a></code>.
</p>
<p>Below we've shown some examples of content locations and their corresponing URL's:</p>
<table>
<tbody>
<tr>
<th style="text-align:left">Physical Location</th>
<th style="text-align:left">URL</th>
</tr>
<tr>
<td>content-sample/index.md</td>
<td>/</td>
</tr>
<tr>
<td>content-sample/sub.md</td>
<td>/sub</td>
</tr>
<tr>
<td>content-sample/sub/index.md</td>
<td>/sub (same as above)</td>
</tr>
<tr>
<td>content-sample/sub/page.md</td>
<td>/sub/page</td>
</tr>
<tr>
<td>content-sample/a/very/long/url.md&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>/a/very/long/url</td>
</tr>
</tbody>
</table><br />
<p>If a file cannot be found, the file <code>content-sample/404.md</code> will be shown.</p>
<h4 id="text-file-markup">Text File Markup</h4>
<p>
Text files are marked up using <a href="http://daringfireball.net/projects/markdown/syntax">Markdown</a>.
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:
</p>
<pre><code>
/*
Title: Welcome
Description: This description will go in the meta description tag
Author: Joe Bloggs
Date: 2013/01/01
Robots: noindex,nofollow
Template: index (allows you to use different templates in your theme)
*/
</code></pre>
<p>
These values will be contained in the <code>{% raw %}{{ meta }}{% endraw %}</code> variable in themes (see below).
There are also certain variables that you can use in your text files:
</p>
<ul>
<li>%base_url% - The URL to your Pico site</li>
</ul>
<hr>
<h3 id="themeing">Themeing</h3>
<p>
You can create themes for your Pico installation and in the "themes" folder. Check out the default theme for an example of a theme. Pico uses
<a href="http://twig.sensiolabs.org/documentation">Twig</a> for it's templating engine. You can select your theme by setting the <code>$config['theme']</code> variable
in <code>config/config.php</code> to your theme folder.
</p>
<p>All themes must include an <code>index.html</code> file to define the HTML structure of the theme. Below are the Twig variables that are available to use in your theme:</p>
<ul>
<li><code>{% raw %}{{ config }}{% endraw %}</code> - Conatins the values you set in <code>config/config.php</code> (e.g. <code>{% raw %}{{ config.theme }}{% endraw %}</code> = "default")</li>
<li><code>{% raw %}{{ base_dir }}{% endraw %}</code> - The path to your Pico root directory</li>
<li><code>{% raw %}{{ base_url }}{% endraw %}</code> - The URL to your Pico site</li>
<li><code>{% raw %}{{ theme_dir }}{% endraw %}</code> - The path to the Pico active theme direcotry</li>
<li><code>{% raw %}{{ theme_url }}{% endraw %}</code> - The URL to the Pico active theme direcotry</li>
<li><code>{% raw %}{{ site_title }}{% endraw %}</code> - Shortcut to the site title (defined in <code>config/config.php</code>)</li>
<li>
<code>{% raw %}{{ meta }}{% endraw %}</code> - Contains the meta values from the current page
<ul>
<li><code>{% raw %}{{ meta.title }}{% endraw %}</code></li>
<li><code>{% raw %}{{ meta.description }}{% endraw %}</code></li>
<li><code>{% raw %}{{ meta.author }}{% endraw %}</code></li>
<li><code>{% raw %}{{ meta.date }}{% endraw %}</code></li>
<li><code>{% raw %}{{ meta.date_formatted }}{% endraw %}</code></li>
<li><code>{% raw %}{{ meta.robots }}{% endraw %}</code></li>
</ul>
</li>
<li><code>{% raw %}{{ content }}{% endraw %}</code> - The content of the current page (after it has been processed through Markdown)</li>
<li>
<code>{% raw %}{{ pages }}{% endraw %}</code> - A collection of all the content in your site
<ul>
<li><code>{% raw %}{{ page.title }}{% endraw %}</code></li>
<li><code>{% raw %}{{ page.url }}{% endraw %}</code></li>
<li><code>{% raw %}{{ page.author }}{% endraw %}</code></li>
<li><code>{% raw %}{{ page.date }}{% endraw %}</code></li>
<li><code>{% raw %}{{ page.date_formatted }}{% endraw %}</code></li>
<li><code>{% raw %}{{ page.content }}{% endraw %}</code></li>
<li><code>{% raw %}{{ page.excerpt }}{% endraw %}</code></li>
</ul>
</li>
<li><code>{% raw %}{{ prev_page }}{% endraw %}</code> - A page object of the previous page (relative to current_page)</li>
<li><code>{% raw %}{{ current_page }}{% endraw %}</code> - A page object of the current_page</li>
<li><code>{% raw %}{{ next_page }}{% endraw %}</code> - A page object of the next page (relative to current_page)</li>
<li><code>{% raw %}{{ is_front_page }}{% endraw %}</code> - A boolean flag for the front page</li>
</ul>
<p>Pages can be used like:</p>
<pre>{% raw %}&lt;ul class="nav"&gt;
{% for page in pages %}
&lt;li&gt;&lt;a href="{{ page.url }}"&gt;{{ page.title }}&lt;/a&gt;&lt;/li&gt;
{% for doc in site.docs %}
<!-- path = {{ doc.path }} -->
{{ doc.output }}
{% endfor %}
&lt;/ul&gt;{% endraw %}</pre>
<h4 id="blogging">Blogging</h4>
<p>If you would like to add a blog to your Pico site we suggest taking the following steps:</p>
<ul>
<li>Put all of your post .md files in your content-sample folder</li>
<li>
Make sure you add a "Date" field to all of your post .md files in the content-sample folder so you can distinguish between
posts and pages (i.e. posts will have a "Date", pages won't)
</li>
<li>In your template do something like this:</li>
</ul>
<pre>{% raw %}{% if is_front_page %} &lt;!-- Front page lists all blog posts --&gt;
&lt;div id=&quot;posts&quot;&gt;
{% for page in pages %}
{% if page.date %} &lt;!-- Note we check for Date field (posts) here --&gt;
&lt;div class=&quot;post&quot;&gt;
&lt;h3&gt;&lt;a href=&quot;{{ page.url }}&quot;&gt;{{ page.title }}&lt;/a&gt;&lt;/h3&gt;
&lt;p class=&quot;meta&quot;&gt;{{ page.date_formatted }}&lt;/p&gt;
&lt;p class=&quot;excerpt&quot;&gt;{{ page.excerpt }}&lt;/p&gt;
&lt;/div&gt;
{% endif %}
{% endfor %}
&lt;/div&gt;
{% else %} &lt;!-- Single page shows individual blog post --&gt;
&lt;div class=&quot;post&quot;&gt;
{% if meta.title %}&lt;h2&gt;{{ meta.title }}&lt;/h2&gt;{% endif %}
&lt;p class=&quot;meta&quot;&gt;{{ meta.date_formatted }}&lt;/p&gt;
{{ content }}
&lt;/div&gt;
{% endif %}{% endraw %}</pre>
<hr>
<h3 id="plugins">Plugins</h3>
<p>
<a href="plugins.html">Plugins</a> can be created by creating a new PHP file and placing it in the "plugins" folder. Plugins can be placed
in a sub folder if required. In your new plugin PHP file you need to create class with the <strong>same name</strong> as
the file. So if you create a file called <code>my_plugin.php</code> your class needs to be called <code>My_Plugin</code>.
</p>
<p>
Plugins can hook into Pico by adding functions with predefined names (hooks) to their class. For example you could
add a custom template variable by adding a <code>before_render</code> hook:
</p>
<pre>class My_Plugin {
public function before_render(&$twig_vars, &$twig)
{
// Add a custom template variable
$twig_vars['my_custom_var'] = 'Hello World';
}
}</pre>
<p>Below is a list of available hooks and their parameters:</p>
<ul>
<li><code>plugins_loaded()</code></li>
<li><code>config_loaded(&$settings)</code></li>
<li><code>request_url(&$url)</code></li>
<li><code>before_load_content(&$file)</code></li>
<li><code>after_load_content(&$file, &$content)</code></li>
<li><code>before_404_load_content(&$file)</code></li>
<li><code>after_404_load_content(&$file, &$content)</code></li>
<li><code>before_read_file_meta(&$headers)</code></li>
<li><code>file_meta(&$meta)</code></li>
<li><code>before_parse_content(&$content)</code></li>
<li><code>after_parse_content(&$content)</code></li>
<li><code>get_page_data(&$data, $page_meta)</code></li>
<li><code>get_pages(&$pages, &$current_page, &$prev_page, &$next_page)</code></li>
<li><code>before_twig_register()</code></li>
<li><code>before_render(&$twig_vars, &$twig, &$template)</code></li>
<li><code>after_render(&$output)</code></li>
</ul>
<p>
Note that parameter variables are <a href="http://php.net/manual/en/language.references.pass.php" target="_blank">passed by reference</a>
so that they can be modified.
</p>
<h4 id="adding-custom-meta">Adding Custom Meta</h4>
<p>If you need to add custom meta variables you can do so using the <code>before_read_file_meta()</code> hook. For example:</p>
<pre><code>public function before_read_file_meta(&$headers)
{
$headers['layout'] = 'Layout';
}</code></pre>
<p>Then in your content meta you would add the relevant meta value:</p>
<pre><code>/*
Title: Example
Description: This is a description
Layout: 2col
*/
</code></pre>
<p>You will then be able to access this value via the <code>{% raw %}{{ meta.layout }}{% endraw %}</code> template variable.</p>
<hr>
<h3 id="contribute">Contribute</h3>
<p>
Help make Pico better by checking out <a href="https://github.com/picocms/Pico">the GitHub repository</a> and submitting pull requests. If you find a bug
please report it on <a href="https://github.com/picocms/Pico/issues">the issues page</a>.
</p>
<hr>
</div>