@synion/md-docs
v1.1.13
Published
Business driven living documentation static site generator.
Downloads
466
Maintainers
arjangeertsemaReadme
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.ymlanchor is automatically converted into a model viewer; - Every
*.bpmnanchor is automatically converted into a BPMN.io viewer; - Every
*openapi.yamlanchor is automatically converted into a HTML documentation page; - Every
*.featureanchor is automatically converted into a feature details list; - Every
*.dashboard.yamlanchor is automatically converted into a BDD dashboard; - Every
*.user-task.yamlanchor is automatically converted into a user-interface; - Every
*.pumlfiler is automatically converted into an SVG image file; - Every
*.drawiofile is automatically into an SVG image file; - Every
*.java,*.cs,*.ts,*.js,*.json,*.py,*.yml,*.ymlanchor 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.
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.htmlOptions
branches only
md-docs -bCustom 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 branch2To debug
Set the environment to development. All intermediate steps are saved as files in the dist directory.
export NODE_ENV=development