Welcome to markdown-docs generator!

Getting Started

First install the package

npm i simple-markdown-docs

Then initialize the default documentation structure

npx init-docs

Overview

It is very simple to get started. First we need to have a docs folder. It will contain all the documentation, by groups.

Each group is represented by a folder. That can contain as many documents as you want. Each group can have a config.json file, which can contain some settings for each group. In the docs directory you need to have a config.json file, which contains the settings for the whole documentation.

An example directory structure maybe.

docs
├── group1
│   ├── Doc1.md
│   ├── Doc2.md
│   ├── Doc3.md
│   └── config.json (optional)
├── group2
│   ├── Doc1.md
│   ├── Doc2.md
├── config.json (required)

Global Configuration

Under the docs folder there is a config.json file, which contains the settings for the documentation. The default configuration is as follows:

{
    "name": "Markdown Docs",
    "version": "1.0.0",
    "description": "Markdown Docs",
    "groupOrder": [
        "Introduction"
    ],
    "outputPath": "./docs/dist/",
    "autoGenerate": true,
    "generateOnRequest": false,
}

| Property | Description | type | Required | | -------- | ----------- | ----------- | ----------- | | name | The title of the documentation. | string | Yes | | version | The version of the documentation. | string | No | | description | The description of the documentation. | string | No | | groupOrder | The order of the groups. (names must match directory structure) | array of strings | No | | outputPath | The output path of the documentation. | string | No | | autoGenerate | If true the documentation will be generated automatically on server start. | boolean | No | | generateOnRequest | If true the documentation will be generated automatically when requested. | boolean | No |

If you specify a generateOnRequest property, you will need to add a route to your server. See the integrating with express documentation for more information.

If you specify the groupOrder property in the config.json file, the groups will be rendered in the order specified. Any files that are not in the groupOrder array will be rendered at the end of the documentation alphabetically. For example lets say we had the following directory structure:

docs
├── A
├── B
├── C
├── config.json (required)

and we set our group order to be

{
    "groupOrder": [
        "C"
    ]
}

Our output will be ordered as follows:

C
A
B

Group Configuration

Under any/all of your groups you can specify a config.json file, which contains the settings for the group. The default configuration is as follows:

{
    "groupName": "Example Documents",
    "groupDescription": "Example documents for testing",
    "order": [
        "ApiRoute2.md",
        "ApiRoute1.md"
    ],
    "rename": {
        "ApiRoute1.md": "Example #1",
        "ApiRoute2.md": "Example #2"
    }
}

| Property | Description | type | Required | | -------- | ----------- | ----------- | ----------- | | groupName | The name of the group. | string | No | | groupDescription | The description of the group. | string | No | | order | The order of the documents. (names must match file names .md optional) | array of strings | No | | rename | A map of old names to new names. | object | No |

If you specify the order property in the config.json file, the documents will be rendered in the order specified. Any files that are not in the groupOrder array will be rendered at the end of the documentation alphabetically. See the notes about the groupOrder property for more information and an example.

If you specify the rename property in the config.json file, the documents will be renamed as specified. For example lets say we had the following directory structure:

docs
├── group1
│   ├── Doc1.md
│   ├── Doc2.md
│   ├── Doc3.md
│   └── config.json (optional)

and we set our rename property to be

{
    "rename": {
        "Doc1.md": "Example #1",
        "Doc2.md": "Example #2"
    }
}

Our documentation structure will be as follows:

Example #1
Example #2
Doc3

Integrating with Express

const app = require('express');
const route = require('simple-markdown-docs').express.route;
// Docs will be added to your routes by going to `/docs`
app.use(route(
    //Optionally specify the top level configuration
    {
        name: "Markdown Docs",
        version: "1.0.0",
        description: "Markdown Docs",
        groupOrder: [
            "Introduction"
        ],
        outputPath: "./docs/dist/",
        autoGenerate: false,
        generateOnRequest: true
    }
));

Customizing the Documentation Template

We use the handlebars templating engine to render the documentation. The default template is located in the /docs directory. You can customize the template by replacing the template.handlebars.

The following template variables are the default:

• Documentation Name
  • {{config.name}}
• Navigation Links HTML
  • {{{nav}}}
• Body HTML
  • {{{content}}}

The template variables available to you are:

config

{{config}}

All the properties from the top-level configuration file.

| Property | Description | type | Required | | -------- | ----------- | ----------- | ----------- | | groupName | The name of the group. | string | No | | groupDescription | The description of the group. | string | No | | order | The order of the documents. (names must match file names .md optional) | array of strings | No | | rename | A map of old names to new names. | object | No |

content

{{{content}}}

The body of the documentation, as HTML.

nav

{{nav}}

The navigation links for the documentation, formatted as HTML.

<li><a href="#group-Introduction">Introduction</a></li>
<li><a href="#Index" class="sub">Index</a></li>

navLinks

{{navLinks}}

The navigation links for the documentation, as an object.

[
  {
    "id": "group-Introduction",
    "name": "Introduction",
    "sub": [
      {
        "name": "Index",
        "id": "Index"
      }
    ]
  },
  {
    "id": "group-Example",
    "name": "Example Documents",
    "sub": [
      {
        "name": "Example #2",
        "id": "ApiRoute2"
      },
      {
        "name": "Example #1",
        "id": "ApiRoute1"
      }
    ]
  }
]

structure

{{structure}}

The structure of the documentation, as an object.

{
  "Example": {
    "_files": [
      "./docs/groups/Example/ApiRoute1.md",
      "./docs/groups/Example/ApiRoute2.md"
    ],
    "_ids": [
      "ApiRoute1",
      "ApiRoute2"
    ],
    "ApiRoute1": "<div class=\"markdown-body\" id=\"ApiRoute1\"><h2 class=\"md-h2\"  id=\"first-example-of-a-markdown-file\">First example of a markdown file</h2></div>",
    "_config": {
      "groupName": "Example Documents",
      "groupDescription": "Example documents for testing",
      "order": [
        "ApiRoute2.md",
        "ApiRoute1.md"
      ],
      "rename": {
        "ApiRoute1": "Example #1",
        "ApiRoute2": "Example #2"
      }
    },
    "ApiRoute2": "<div class=\"markdown-body\" id=\"ApiRoute2\"><h2 class=\"md-h2\"  id=\"second-example\">Second Example</h2></div>"
  },
  "Introduction": {
    "_files": [
      "./docs/groups/Introduction/Index.md"
    ],
    "_ids": [
      "Index"
    ],
    "Index": "<div class=\"markdown-body\" id=\"Index\"><h2 class=\"md-h2\"  id=\"introduction\">Introduction</h2></div>"
  }
}

Plans for the future

• [ ] Add support for custom markdown
• [ ] Add support for auto-generating documentation for express
• [ ] Improve template