Updating docs.

docs.html

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