@synion/md-docs

Living documentation

See product documentation for more information.

To get started

npm install @synion/md-docs -g
mkdir ../documentation
cd documentation
mkdir docs
echo "# It works!" > docs/index.md
md-docs
google-chrome dist/index.html

Options

branches only

md-docs -b

Custom theme

You can override all assets files by adding the same files to docs folder: docs/assets/style/custom-theme.css can then be overwritten by a custom theme implementation.

Skip branches

md-docs -s branch1 branch2

To debug

Set the environment to development. All intermediate steps are saved as files in the dist directory.

export NODE_ENV=development

Product

md-docs is a cli tool which generates a static webiste by resolving files recursivly from a source folder.

This script copies every file and directory from the docs directory into the dist directory and transforms every *.md file into a html file while adding the following features:

1. Every *.md is transformed in a static web page;
2. Every *.message.md is transformed in a static document web page and PDF;
3. Every index.md is added to the menu;
4. Every heading is automaticly converted into a container;
5. Every *.bpmn anchor is automaticly converted into a bpmn.io viewer;fir
6. Every *openapi.yaml anchor is automaticly converted into a html documentation page;
7. Every *asyncapi.yaml anchor is automaticly converted into a html documentation page;
8. Every *.feature anchor is automaticly converted into a feature details list;
9. Every *.dashboard.yaml anchor is automaticly converted into a BDD dashboard;
10. Every *.user-task.yaml anchor is automaticly converted into a user-interface;
11. Every *.puml filer is automaticly converted into an svg image file;
12. Every *.drawio file is automaticly into an svg image file;
13. Every *.java, *.cs, *.ts, *.js, *.json, *.py, *.yml, *.yml anchor is automaticly converted in a code block;
14. Every markdown anchor is automaticly converted into an html link;
15. Every markdown anchor which starts with an _ is automaticly added to the markdown file;
16. Every git branch is added to the git menu;
17. Test executions are automaticly parsed in feature files;
18. Unsorted list with items which reference the files above are automaticly converted in tab panels;
19. Images are wrapped in figures;
20. Images can be alligned by adding align=center or align=left or align=right to the url;
21. Markdown is transformed into html using markdow-it, the following plugins are installed:
    • markdown-it-multimd-table => additional table options;
    • markdown-it-container => info, warning and error containers;
    • markdown-it-toc-done-right => table of contents for h1, h2 and h3;
    • markdown-it-plantuml-ex => UML is automaticly converted into a SVG;
    • markdown-it-abbr;
    • markdown-it-codetabs;
    • markdown-it-attrs;

All links are relative so you do not need a webserver.

Architecture

The application is written in node js and implements a plug in architecture. It uses Awilix under the hood for dependency resolving. Plugins can be used by extending App and adding or replacing service registrations.

There are several plugin strategies:

1. add or change the file parsers;
2. add or change the html parsers;
3. add or change the anchor parsers;
4. change components;
5. change component render functions;

module.exports = MyApp extends App {
    constructor(options) {
        super(options);
    }

    _getServices(options) {
        const services = super(options);

        //Option 1
        services['newFileParser'] = asClass(NewFileParser).singleton();
        services.fileParsers.push('newFileParser');

        //Option 2
        services['newHtmlParser'] = asClass(NewHtmlParser).singleton();
        services.htmlParsers.push('newHtmlParser');


        //Option 3
        services['newAnchorParser'] = asClass(NewAnchorParser).singleton();
        services.anchorParsers.push('newAnchorParser');
        
        //Option 4
        services.pageComponent = asClass(MyPageComponent).singleton();

        //Option 5
        services.pageComponentRenderFn = asValue((data) => '<html />');

        return services;
    }
}

Class diagram