updated doc

README.md

@@ -1,35 +1,98 @@
-# GitBlog.md (WIP)
+# GitBlog.md
-> This is a work in progress, some information written here might not be true yet.
 
 [![Build Status](https://img.shields.io/travis/Klemek/GitBlog.md.svg?branch=master)](https://travis-ci.org/Klemek/GitBlog.md)
 [![Coverage Status](https://img.shields.io/coveralls/github/Klemek/GitBlog.md.svg?branch=master)](https://coveralls.io/github/Klemek/GitBlog.md?branch=master)
 
 A static blog using Markdown pulled from your git repository.
 
-## Flow
+* **[How it works](#how-it-works)**
+* **[Installation](#installation)**
+* **[Writing an article](#writing-an-article)**
+* **[Configuration](#configuration)**
+
+## How it works
+[back to top](#gitblog-md)
+
+There are 4 majors features of this project :
+
+#### 1. Home page
+
+<details>
+<summary>diagram (click)</summary>
+<p>
 
 ![root](./uml/root.png)
+</p>
+</details>
+
+When you access the root url of your blog, the app will fetch the template and inject the list of currently available articles.
+
+
+#### 2. Article page
+
+<details>
+<summary>diagram (click)</summary>
+<p>
 
 ![article](./uml/article.png)
+</p>
+</details>
+
+As you access an article link, the server will fetch it's `index.md` Markdown file and render it in plain HTML using Showdown.
+
+
+#### 3. Git webhook
+
+<details>
+<summary>diagram (click)</summary>
+<p>
 
 ![webhook](./uml/webhook.png)
+</p>
+</details>
+
+As you configured your data repository, when you push any data, it will trigger the webhook that will perform a `git pull` then refresh the data you just committed.
+
+
+#### 4. RSS feed
+
+<details>
+<summary>diagram (click)</summary>
+<p>
 
 ![rss](./uml/rss.png)
+</p>
+</details>
+
+On the `/rss` endpoint, the servers gives you a RSS feed based on the list of articles which you can bookmark.
+
+
 
 ## Installation
-**1. Download and install the latest version from the repo**
+[back to top](#gitblog-md)
+
+#### 1. Download and install the latest version from the repo
 ```bash
 git clone https://github.com/klemek/gitblog.md.git
 npm install
 ```
-**2. Create your config file**
+#### 2. Create your config file
 ```bash
 cd gitblog.md
 cp config.example.json config.json
 ```
 then edit the config.json file with your custom values.
+For example, you might want to change the app's port with :
 
-**3. Start your server**
+```json
+{
+  "node_port": 3030
+}
+```
+
+See [Configuration](#configuration) for more info.
+
+#### 3. Start your server
 
 ```bash
 npm run
@@ -37,9 +100,18 @@ npm run
 node src/server.js
 ```
 
+You can check that it's up and running at [http://localhost:3000/](http://localhost:3000/)
+
 You might want to use something like screen to separate the process from your current terminal session.
 
-**4. Create and init your git source**
+#### 4. Customize the blog's style
+
+At `npm install` a first article will be created for the current date.
+You see it as an example of rendering of your blog.
+Use it to edit your templates and styles located on the `data` folder.
+At first, home page and articles are rendered using EJS engine but you can customize that into the configuration.
+
+#### 5. Create and init your git source
 
 You need to [create a new repository](https://github.com/new) on your favorite Git service.
 
@@ -50,7 +122,9 @@ git remote add origin <url_of_your_repo.git>
 git push -u origin master
 ```
 
-**5. Refresh content with a webhook (optional)**
+Now you just have to edit a local copy of your articles and, when you push them, to perform a simple `git pull` on that data folder.
+
+#### 6. Refresh content with a webhook (optional)
 
 Create a webhook on your git source (On GitHub, in the `Settings/Webhooks` part of the repository.) with the following parameters :
 
@@ -58,23 +132,102 @@ Create a webhook on your git source (On GitHub, in the `Settings/Webhooks` part
 * Content type : `application/json`
 * Events : Just the push event
 
-**6. Securize your webhook (optional)**
+Now the server will perform the `git pull` task for you after a successful push on GitHub.
+
+#### 7. Securize your webhook (optional)
 
 Here are the steps for Github, if you use another platform adapt it your way (header format on the config) :
 
 * Create a password or random secret
 * Edit your configuration to add webhook info 
 ```json
-{
-...
 "webhook": {
     "endpoint": "/webhook",
     "secret": "sha1=<value>",
     "signature_header": "X-Hub-Signature"
   },
-...
-}
 ```
 * Launch the server
 * Update your webhook on github to include the secret
-* Check if Github successfully reached the endpoint
+* Check if Github successfully reached the endpoint
+
+## Writing an article
+[back to top](#gitblog-md)
+
+TODO
+
+## Configuration
+[back to top](#gitblog-md)
+
+*  `node_port` (default: 3000)
+   
+   the port the server is listening to
+* `data_dir` (default: data)
+
+   the directory where will be located the git repo with templates and articles
+* `view_engine` (default: ejs)
+
+   the Express view engine used to render pages from templates
+* `modules`
+   * `rss` (default: true)
+   
+      activate the RSS endpoint and its features
+   * `webhook` (default: true)
+   
+      activate the webhook endpoint and its features
+   * `prism` (default: true)
+   
+      activate Prism code highlighting
+* `home`
+   * `index` (default: index.ejs)
+   
+      the name of the home page template on the data directory
+      
+      it will receive `articles`, a list of articles for rendering
+   * `error` (default: error.ejs)
+   
+      the name of the error page template on the data directory
+      
+      it will receive `error`, the error code
+   * `hidden` (default: `[.ejs]`)
+   
+      file extensions to be returned 404 when reached
+* `article`
+   * `index` (default: index.md)
+   
+      the name of the Markdown page of the article on the `/year/month/day/` directory
+   * `template` (default: template.ejs)
+   
+      the name of the article page template on the data directory
+   * `thumbnail_tag`: (default: thumbnail)
+   
+      the alt text searched to get the thumbnail image on the article
+      
+      as in `![<thumbnail_tag>](<url of the image>)`
+   * `default_title`: (default: Untitled)
+   
+      the title of the article in case a level 1 title was not found
+   * `default_thumbnail`: (default: none)
+   
+      the path of the default thumbnail to get from the data directory
+* `rss`
+   * `title`: (default: mygitblog RSS feed)
+   * `description`: (default: a generated RSS feed from my articles)
+   * `endpoint`: (default: /rss)
+   * `length`: (default: 10)
+   
+      how many last articles will be present in the feed
+* `webhook`
+   * `endpoint`: (default: /webhook)
+   * `secret`: (default: none)
+      
+      see [above](#7-securize-your-webhook-optional-)
+   * `signature_header`: (default: none)
+   
+      see [above](#7-securize-your-webhook-optional-)
+   * `pull_command`: (default: git pull)
+   
+      the command used by the server on webhook trigger
+* `showdown`
+
+   Options to be applied to Showdown renderer (see [showdown options](https://github.com/showdownjs/showdown#valid-options) for more info)

src/config.default.json

@@ -2,9 +2,7 @@
   "node_port": 3000,
   "data_dir": "data",
   "view_engine": "ejs",
-  "language": "en-us",
   "modules": {
-    "plantuml": false,
     "rss": true,
     "webhook": true,
     "prism": true