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

Updating docs.

Browse source
This commit is contained in:
Gilbert Pellegrom 2013-05-07 12:44:14 +01:00
parent 40f06ba352
commit bd10990a43
1 changed files with 191 additions and 107 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

298
docs.html
View file

@ -76,65 +76,80 @@
<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 />You simply create .txt files in the "content" folder and that becomes a page.</p>
<br />You simply create .md files in the "content" folder and that becomes a page.</p>
<br />
<h3>Requirements</h3>
<p>To run Pico you simple need <strong>PHP 5.2.4+</strong> to be running on your server. If you're running Apache you will
also require <code>mod_rewrite</code> to be enabled.</p>
<hr>
<h3>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>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 config.php in the root Pico directory. The config.php file
lists all of the settings and their defaults. To override a setting simply uncomment it in config.php and set your custom value.</p>
<hr>
<h3>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>.txt</code> files in the "content"
folder and that becomes a page.</p>
<p>If you created folder within the content folder (e.g. <code>content/sub</code>) and put an <code>index.txt</code> inside it, you can access that folder at the URL
<code><a href="http://yousite.com/sub">http://yousite.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/sub/page.txt</code>)
and will be able to access it from the URL <code><a href="http://yousite.com/sub/page">http://yousite.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/index.txt</td>
<td>/</td>
</tr>
<tr>
<td>content/sub.txt</td>
<td>/sub</td>
</tr>
<tr>
<td>content/sub/index.txt</td>
<td>/sub (same as above)</td>
</tr>
<tr>
<td>content/sub/page.txt</td>
<td>/sub/page</td>
</tr>
<tr>
<td>content/a/very/long/url.txt&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/404.txt</code> will be shown.</p>
<h4>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>/*
<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></li>
<li><a href="#contribute">Contribute</a></li>
</ul>
</div>
<div class="three-fourth last">
<h3 id="requirements">Requirements</h3>
<p>To run Pico you simple need <strong>PHP 5.2.4+</strong> to be running on your server. If you're running Apache you will
also 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>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 config.php in the root Pico directory. The config.php file
lists all of the settings and their defaults. To override a setting simply uncomment it in config.php 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>.txt</code> files in the "content"
folder and that becomes a page.</p>
<p>If you created folder within the content folder (e.g. <code>content/sub</code>) and put an <code>index.txt</code> inside it, you can access that folder at the URL
<code><a href="http://yousite.com/sub">http://yousite.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/sub/page.txt</code>)
and will be able to access it from the URL <code><a href="http://yousite.com/sub/page">http://yousite.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/index.txt</td>
<td>/</td>
</tr>
<tr>
<td>content/sub.txt</td>
<td>/sub</td>
</tr>
<tr>
<td>content/sub/index.txt</td>
<td>/sub (same as above)</td>
</tr>
<tr>
<td>content/sub/page.txt</td>
<td>/sub/page</td>
</tr>
<tr>
<td>content/a/very/long/url.txt&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/404.txt</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
@ -142,59 +157,128 @@ Date: 2013/01/01
Robots: noindex,nofollow
*/
</code></pre>
<p>These values will be contained in the <code>{{ meta }}</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>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 config.php 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>{{ config }}</code> - Conatins the values you set in config.php (e.g. <code>{{ config.theme }}</code> = "default")</li>
<li><code>{{ base_dir }}</code> - The path to your Pico root directory</li>
<li><code>{{ base_url }}</code> - The URL to your Pico site</li>
<li><code>{{ theme_dir }}</code> - The path to the Pico active theme direcotry</li>
<li><code>{{ theme_url }}</code> - The URL to the Pico active theme direcotry</li>
<li><code>{{ site_title }}</code> - Shortcut to the site title (defined in config.php)</li>
<li><code>{{ meta }}</code> - Contains the meta values from the current page
<ul>
<li><code>{{ meta.title }}</code></li>
<li><code>{{ meta.description }}</code></li>
<li><code>{{ meta.author }}</code></li>
<li><code>{{ meta.date }}</code></li>
<li><code>{{ meta.date_formatted }}</code></li>
<li><code>{{ meta.robots }}</code></li>
</ul></li>
<li><code>{{ content }}</code> - The content of the current page (after it has been processed through Markdown)</li>
<li><code>{{ pages }}</code> - A collection of all the content in your site
<ul>
<li><code>{{ page.title }}</code></li>
<li><code>{{ page.url }}</code></li>
<li><code>{{ page.author }}</code></li>
<li><code>{{ page.date }}</code></li>
<li><code>{{ page.date_formatted }}</code></li>
</ul></li>
<li><code>{{ prev_page }}</code> - A page object of the previous page (relative to current_page)</li>
<li><code>{{ current_page }}</code> - A page object of the current_page</li>
<li><code>{{ next_page }}</code> - A page object of the next page (relative to current_page)</li>
<li><code>{{ is_front_page }}</code> - A boolean flag for the front page</li>
</ul>
<p>Pages can be used like:</p>
<pre>&lt;ul class="nav"&gt;
<p>These values will be contained in the <code>{{ meta }}</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 config.php 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>{{ config }}</code> - Conatins the values you set in config.php (e.g. <code>{{ config.theme }}</code> = "default")</li>
<li><code>{{ base_dir }}</code> - The path to your Pico root directory</li>
<li><code>{{ base_url }}</code> - The URL to your Pico site</li>
<li><code>{{ theme_dir }}</code> - The path to the Pico active theme direcotry</li>
<li><code>{{ theme_url }}</code> - The URL to the Pico active theme direcotry</li>
<li><code>{{ site_title }}</code> - Shortcut to the site title (defined in config.php)</li>
<li><code>{{ meta }}</code> - Contains the meta values from the current page
<ul>
<li><code>{{ meta.title }}</code></li>
<li><code>{{ meta.description }}</code></li>
<li><code>{{ meta.author }}</code></li>
<li><code>{{ meta.date }}</code></li>
<li><code>{{ meta.date_formatted }}</code></li>
<li><code>{{ meta.robots }}</code></li>
</ul></li>
<li><code>{{ content }}</code> - The content of the current page (after it has been processed through Markdown)</li>
<li><code>{{ pages }}</code> - A collection of all the content in your site
<ul>
<li><code>{{ page.title }}</code></li>
<li><code>{{ page.url }}</code></li>
<li><code>{{ page.author }}</code></li>
<li><code>{{ page.date }}</code></li>
<li><code>{{ page.date_formatted }}</code></li>
<li><code>{{ page.content }}</code></li>
<li><code>{{ page.excerpt }}</code></li>
</ul></li>
<li><code>{{ prev_page }}</code> - A page object of the previous page (relative to current_page)</li>
<li><code>{{ current_page }}</code> - A page object of the current_page</li>
<li><code>{{ next_page }}</code> - A page object of the next page (relative to current_page)</li>
<li><code>{{ is_front_page }}</code> - A boolean flag for the front page</li>
</ul>
<p>Pages can be used like:</p>
<pre>&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;
{% endfor %}
&lt;/ul&gt;</pre>
<p>Note the <code>{{ pages }}</code> objects don't contain <code>content</code>. It is mainly to be used in creating navigaiton.</p>
<hr>
<h3>Contribute</h3>
<p>Help make Pico better by checking out <a href="https://github.com/gilbitron/Pico">the GitHub repoistory</a> and submitting pull requests. If you find a bug
please report it on <a href="https://github.com/gilbitron/Pico/issues">the issues page</a>.</p>
<hr>
<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 folder</li>
<li>Make sure you add a "Date" field to all of your post .md files in the content 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>{% 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 %}</pre>
<hr>
<h3 id="plugins">Plugins</h3>
<p>Plugins 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>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>config_loaded(&$settings)</code></li>
<li><code>file_meta(&$meta)</code></li>
<li><code>content_parsed(&$content)</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)</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>
<hr>
<h3 id="contribute">Contribute</h3>
<p>Help make Pico better by checking out <a href="https://github.com/gilbitron/Pico">the GitHub repoistory</a> and submitting pull requests. If you find a bug
please report it on <a href="https://github.com/gilbitron/Pico/issues">the issues page</a>.</p>
<hr>
</div>
<div class="clear"></div>
</div>
<!-- End Inner -->
</div>