@synion/md-docs NPM

Product

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

See the test set for more information.

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:

Every *.md is transformed in a static web page;
Every *.email.md is transformed in a static document web page;
Every *.message.md is transformed in a static document web page and PDF;
Every index.md is added to the menu;
Every heading is automatically converted into a container;
Every *.model.yml anchor is automatically converted into a model viewer;
Every *.bpmn anchor is automatically converted into a BPMN.io viewer;
Every *openapi.yaml anchor is automatically converted into a HTML documentation page;
Every *.feature anchor is automatically converted into a feature details list;
Every *.dashboard.yaml anchor is automatically converted into a BDD dashboard;
Every *.user-task.yaml anchor is automatically converted into a user-interface;
Every *.puml filer is automatically converted into an SVG image file;
Every *.drawio file is automatically into an SVG image file;
Every *.java, *.cs, *.ts, *.js, *.json, *.py, *.yml, *.yml anchor is automatically converted in a code block;
Every markdown anchor is automatically converted into an HTML link;
Every markdown anchor which starts with a _ is automatically added to the markdown file;
Every git branch is added to the git menu;
Test executions are automatically parsed in feature files;
Unsorted list with items which reference the files above are automatically converted in tab panels;
Images are wrapped in figures;
Images can be aligned by adding align=center or align=left or align=right to the URL;
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-plantuml-ex => UML is automatically converted into a SVG;
- markdown-it-abbr;
- markdown-it-codetabs;
- markdown-it-attrs;

All links are relative, so you do not need a web server.

Class diagram

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:

add or change the file parsers;
add or change the HTML parsers;
add or change the anchor parsers;
change components;
change component render functions;

const App = require('md-docs-cli/app');

module.exports = class 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;
  }
}

To get started

npm install @biz-dev-ops/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.