Updates docs (#133)

* Update 1.Overview.md * Update 2.Content.md * Update 3.Layouts.md * Update and rename 4.Options.md to 4.Configuration.md
Cecilapp · Aug 31, 2016 · e04c527 · e04c527
1 parent 8cbb80f
commit e04c527
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 26 deletions.
diff --git a/docs/1.Overview.md b/docs/1.Overview.md
@@ -3,7 +3,7 @@
 To create a new website, we need 3 things:
  1. Documents written in [Markdown](https://daringfireball.net/projects/markdown/)
  2. [Twig](http://twig.sensiolabs.org) templates
- 3. [PHPoole CLI](https://github.com/Narno/PHPoole) or a build script
+ 3. [PHPoole CLI](https://github.com/Narno/PHPoole) **or** a build script
 
 ## Content organization
 ```
@@ -17,9 +17,9 @@ To create a new website, we need 3 things:
 |  └─ About.md           <- A Page in the root
 ├─ layouts               <- Contains Twig templates
 |  ├─ _default           <- Contains default templates
-|  |  ├─ list.html       <- Used by a _list_ node type (ie: Section)
-|  |  └─ page.html       <- Used by the _page_ node type
-|  └─ index.html         <- Used by the _homepage_ node type
+|  |  ├─ list.html.twig  <- Used by a 'list' node type (ie: a Section)
+|  |  └─ page.html.twig  <- Used by the 'page' node type
+|  └─ index.html.twig    <- Used by the 'homepage' node type
 └─ static                <- Contains static files
    └─ robots.txt         <- A static file
 ```
@@ -31,7 +31,7 @@ Use [PHPoole](https://github.com/Narno/PHPoole) CLI and run the following comman
 $ phpoole build -s
 ```
 
-Or create a PHP script:
+**Or** create a PHP script:
 ```php
 <?php
 date_default_timezone_set('Europe/Paris');

diff --git a/docs/2.Content.md b/docs/2.Content.md
@@ -1,24 +1,24 @@
 # Content
 
-The content is represented by [Markdown](http://daringfireball.net/projects/markdown/) files, called _Pages_, organized in folders.
+Content is a bunch of [Markdown](http://daringfireball.net/projects/markdown/) files (or plain text files), called _Pages_, organized in folders.
 Folders in the root are called _Section_ (ie: "Blog", "Project", etc.).
 
-## Pages 
+## Pages
 
-A _Page_ can contain a front matter ([YAML](http://www.yaml.org/spec/1.2/spec.html#Preview)) and/or a body ([Markdown](http://daringfireball.net/projects/markdown/syntax)).
+A _Page_ can contain a front matter and/or a body.
 
 ### Front matter
 
-Any file that contains a YAML front matter will be processed to extract some variables. The front matter must be the first thing in the file and must be a valid YAML.
+Any file that contains a front matter will be processed to extract some variables. The front matter must be the first thing in the file and must be a valid [YAML](http://www.yaml.org/spec/1.2/spec.html#Preview).
 
 **Predefined variables**
 
 | Variable      | Description   | Default value                     |
 | ------------- | ------------- | --------------------------------- |
 | title         | Title         | File basename (without extension) |
 | section       | Section       | Root directory of the file path   |
-| layout        | Layout        | See [_Layout fallback logic_]     |
-| date          | Date          | File modification time            |
+| layout        | Layout        | See _Layout fallback logic_       |
+| date          | Date          | File modification datetime        |
 | menu          | Menu          | Homepage and Sections             |
 | tags          | Tags          | _Empty_                           |
 | categories    | Categories    | _Empty_                           |

diff --git a/docs/3.Layouts.md b/docs/3.Layouts.md
@@ -36,7 +36,7 @@ Otherwise:
 
 ### Site
 
-Contains all variables under _site_ key in options.
+Contains all variables under _site_ key in configuration.
 
 | Variable      | Description       |
 | ------------- | ----------------- |
@@ -53,7 +53,7 @@ Menu entry keys:
 
 ### Page
 
-Contains all variables setted in the page's front matter.
+Contains all page variables and those set in the page's front matter.
 
 | Variable        | Description                      | Example       |
 | --------------- | -------------------------------- | ------------- |
@@ -87,11 +87,11 @@ Contains all variables setted in the page's front matter.
 
 ### PHPoole
 
-| Variable          | Description                   |
-| ----------------- | ----------------------------- |
-| phpoole.url       | URL to the official website   |
-| phpoole.version   | Current version               |  
-| phpoole.poweredby | "PHPoole-library v" + version |
+| Variable          | Description                 |
+| ----------------- | --------------------------- |
+| phpoole.url       | URL to the official website |
+| phpoole.version   | Current version             |  
+| phpoole.poweredby | "PHPoole v" + version       |
 
 ## Example
 
@@ -113,6 +113,16 @@ Creates an URL.
 {{ url(page) }}
 {{ url('tags/' ~ tag) }}
 {{ url(menu.url) }}
+{{ url('css/style.css') }}
+{{ url('http://narno.org') }}
+```
+
+#### _minify_
+
+Minify a CSS or a Javascript file.
+```
+{{ minify('css/style.css') }}
+{{ minify('js/script.js') }}
 ```
 
 ### Filters
@@ -145,9 +155,9 @@ Sorts a menu entries collection by weight.
 {{ menu|sortByWeight }}
 ```
 
-#### _filterBySection_
+#### _filterBy_
 
-Filters a pages collection by section name.
+Filters a pages collection by variable name.
 ```
-{{ pages|filterBySection('blog') }}
+{{ pages|filterBy('section', 'blog') }}
 ```
diff --git a/docs/4.Options.md → docs/4.Configuration.md b/docs/4.Options.md → docs/4.Configuration.md
@@ -1,10 +1,10 @@
-# Options
+# Configuration
 
-Options are defined by:
+Configuration is defined by:
 * a YAML file named _phpoole.yml_ with [PHPoole](https://github.com/Narno/PHPoole) CLI
-* a PHP array with PHP script
+* a PHP array (or a _PHPoole\Config_ instance) with PHP script
 
-## Default options
+## Default configuration
 
 ```php
 [
@@ -21,10 +21,14 @@ Options are defined by:
             'max'  => 5,
             'path' => 'page',
         ],
+        'date' => [
+            'format'   => 'j F Y',
+            'timezone' => 'Europe/Paris',
+        ],
     ],
     'content' => [
         'dir' => 'content',
-        'ext' => 'md',
+        'ext' => ['md', 'markdown', 'mdown', 'mkdn', 'mkd', 'text', 'txt'],
     ],
     'frontmatter' => [
         'format' => 'yaml',
@@ -45,5 +49,13 @@ Options are defined by:
     'themes' => [
         'dir' => 'themes',
     ],
+    'generators' => [
+        10 => 'PHPoole\Generator\Section',
+        20 => 'PHPoole\Generator\Taxonomy',
+        30 => 'PHPoole\Generator\Homepage',
+        40 => 'PHPoole\Generator\Pagination',
+        50 => 'PHPoole\Generator\Alias',
+        35 => 'PHPoole\Generator\ExternalBody',
+    ],
 ];
 ```