Skip to content

pilotkid/markdown-docs

Repository files navigation

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

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages