!License
!NPM dependencies

Servedown

Serve your markdown documentations

Why?

- Needed a simple solution to render markdown files in many git projects
- Did not get fully satisfied with gollum or smeagol
- Render docs for read-only usage
- Ability to easily customize styles and templates

Getting started

With a sample configuration, let's serve this project documentation :

- Configuration ~/.servedown.yml :

``yml
repos:
- name: servedown
ssh: git@github.com:openhoat/servedown.git
url: https://github.com/openhoat/servedown
filePattern: /blob/master/{{file}}
`

- Start the server :

`shell
$ servedown
INFO - servedown:181 - 131ms - cloning repo "servedown"...
INFO - servedown:409 - 4.2s - servedown is listening to 0.0.0.0:3000
`

Now your server is ready...

- Browse :

`shell
$ xdg-open http://localhost:3000
`

- Result :

The welcome page is generated from a default template string (or your own index.html)

- Click on "Servedown" doc project :

Now you see your markdown files rendered with styles :-)



Command line

The simplest way to use servedown is the command line.

All you have to do is :

1. setup your servedown configuration file (.servedown.yml) into your home directory
2. run the servedown command

$3

`shell
$ npm i servedown -g
`

$3

Setup your custom configuration in ~/.servedown.yml :

Have a look at the default configuration file to understand all the customizable features.

Starts the servedown doc server :

`shell
$ servedown
`

If repos are specified in configuraton servedown will checkout them into the working directory (~/.servedown), then it will compute recursively the working dir to render the doc site.

Module

If you prefer to embed servedown features into an existing app, then use the servedown module.

$3

`shell
$ cd yournodeproject
$ npm i servedown --save
`

$3

`javascript
const path = require('path');
const ServeDown = require('../lib/servedown');

ServeDown.start( // Factory static helper method
{
cacheDir: path.join(__dirname, '..', 'dist', 'working', 'cache'), // Cache dir
repos: [{ // Git repos to get the markdown docs from
name: 'servedown',
url: 'https://github.com/openhoat/servedown'
}]
})
.then(() => {
console.log('ready');
});
`

or the longer way :

`javascript
const path = require('path');
const express = require('express');
const ServeDown = require('servedown');
const app = express();

const servedown = new ServeDown(); // Create a servedown instance

servedown.init({ // Initialize with custom config
cacheDir: path.join(__dirname, '..', 'dist', 'working', 'cache'), // Cache dir
repos: [{ // Git repos to get the markdown docs from
name: 'servedown',
url: 'https://github.com/openhoat/servedown'
}]
});
app.use(servedown.buildExpressRouter()); // Use provided express middleware
app.listen(3000, () => {
servedown.process(() => { // Prepare html rendering
console.log('ready');
});
});
`

Principles and conventions

Here's a short description of how servedown works :

- servedown first loads the configuration (init)
- if there are git repos, a git pull or clone is executed for each repo
- all source files are scanned
- each markdown file is converted to html content
- html content and meta datas are stored in a filesystem cache (specified by cacheDir in configuration)

Conventions :

- each doc project is associated with a context name (directory of the git url)
- static theme assets are served with /assets/* route
- /search route is reserved to the search form page
- all doc routes are based on the doc file path encoded to a valid uri (lowercase, spaces replaced by '-')
- any doc file name matching the configured index pattern is considered as a welcome page for its parent directory (/mypath/home.md is exposed as /mypath/)

Features

$3

Servedown supports json, js, or yaml format for configuration file.

$3

Prerequisite : git command installed

Add your git repositories and servedown will automatically checkout them.

By default, servedown will optimize the clone operation : only markdown files are fetched.

$3

`
[[ My Title ]]
`

This is shorthand to My Title

#### Include

`
[[ include: my/doc/to/include.md ]]
`

Specified doc path is included into content, relative or absolute paths are supported, file extension is required.

#### Mermaid charts

Embed your Mermaid charts in md content with `mermaid ` tags.

Example :

`
`mermaid

sequenceDiagram

title Authentication Sequence

Alice->Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob->Alice: Authentication Response

`
`

#### Config var injection

First place a config.yml file at the root level of the documentation :

`yaml
myvar: this will be injected
another:
foo: bar
`

Then inject configuration data reference into markdown content using [{ }] tag :

`
[{ myvar }]
`

Another example :

`
[{ another.foo }]
``

Enjoy!