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 :

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

• Start the server :

  $ 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 :

  $ 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

Installation

Prerequisite : install NodeJS

$ npm i servedown -g

Usage

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 :

$ 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.

Installation

$ cd yournodeproject
$ npm i servedown --save

Usage

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 :

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

Configuration format

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

Git support

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.

Theme support

Use one of the two themes provided or use your owns, and hot switch the current theme with ?theme=.

Provided themes :

• github : sample "github like" template
• mydocs (default) : a complete and pretty template with table of contents, breadcrumb, and action buttons
• readthedocs : "readthedocs" like template, for test purpose
• simple : simplest template (no style)

TOC support

Table of contents is dynamically generated from the level 2 headers of markdown contents, look at mydocs theme template example to see how TOC is rendered.

Git source link

Optionnaly show the source link of the current document to make documentation changes easy.

Hot update

Add ?update to your browser address and it will reload, included git update.

Search support

Add ?q=anysearch to your browser address and servedown will search through your docs, show matches in a search result page and highlight the results into the doc content.

Into the doc content, press 'n' or 'p' to go to next/previous matching.

The /search route provides a default search form overridable by search.html theme template.

Markdown extensions

Link title

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

    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 :

myvar: this will be injected
another:
    foo: bar

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

[{ myvar }]

Another example :

[{ another.foo }]

Enjoy!