updated doc
This commit is contained in:
Clément GOUIN
@@ -1,35 +1,98 @@
|
||||
# GitBlog.md (WIP)
|
||||
> This is a work in progress, some information written here might not be true yet.
|
||||
# GitBlog.md
|
||||
|
||||
[](https://travis-ci.org/Klemek/GitBlog.md)
|
||||
[](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>
|
||||
|
||||
|
||||
</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>
|
||||
|
||||
|
||||
</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>
|
||||
|
||||
|
||||
</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>
|
||||
|
||||
|
||||
</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 ``
|
||||
* `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)
|
||||
Reference in New Issue
Block a user