docsMD is a Markdown to HTML generator that converts your README.md (and other .md files) to HTML using node.js.
Install docsMD
$ npm install -g @ckogler/docsmdRun from the command line:
$ docsmd -i readme.md -o ./docs
# or if you installed it without the -g flag:
$ npx docsmd -i readme.md -o ./docsThis will generate docs/index.html from the supplied readme.md file.
docsMD takes all input markdown files and creates a .html file in the output directory with the same name and relative path. If a file is called "readme.md" (or "README.md"), the resulting HTML file will be named "index.html", unless an "index.md" file exists in the same directory.
A directory like this one:
|- readme.md
|- types.md
|- legacy
|- index.md
|- changelog.md
will result in the following file structure (when using default parameters):
|- docs
|- index.html # (renamed from readme.md)
|- types.html
|- legacy
|- index.html
|- changelog.html
Images with a relative URL will be copied to the same relative location in the output directory. That way the resulting HTML files will be able to show the images when the output directory is deployed to a web server. Absolute image URLs will not be touched.
If a link leads to a relative path and ends with ".md", the ending will be replaced with ".html". That way if you can link between .md files will also work in the generated HTML. Absolute links will not be touched.
When genering a single-file documentation the content of multiple individual files might need to be merged together. This is supported by addding a link to the markdown file to include with a text set to '#'. This feature can be disabled with the --inline option.
| Parameter | Explanation |
|---|---|
--input |
The files to convert. Supports the glob pattern. Defaults to **/*.md |
--exclude |
Excludes the matching files from the 'input' parameter. Defaults to node_modules/** |
--output |
The directory where the generated HTML files will be placed. Defaults to ./docs |
--highlight |
Can be true or false. Determines whether highlight.js will be applied to source code. Defaults to true |
--inline |
Can be true or false. Determines whether links with a text set to '#' will be replaced with the included markdown content. |
--template |
Can be used to specify a template file. If none is specified, the included default style will be used. |
Alternatively to the CLI parameters, the configuration can be provided via a docsmd.json file in the executing directory.
A provided CLI parameter will take precedence over the config file.
Example file:
// docsmd.json
{
"input": "**/*.md",
"output": "docs",
"template": "docs-template.html"
}docsMD provides a basic template file, however it is simple to use your own by passing a filename to the "--template" parameter (or template option in the config file). The template file will be reused for each processed .md file
docsMD uses Handlebars internally to apply the template. The template context contains these entries:
| name | description |
|---|---|
content |
The generated HTML content. |
filename |
The name of the currently parsed file (without extension). |
<html>
<head>
<title>{{ filename }}</title>
</head>
<body>
<div>Some header.</div>
<div>
<!-- make sure to use triple braces for the content, so HTML is not escaped! -->
{{{ content }}}
</div>
<div>Some footer.</div>
</body>
</html>The idea behind this package is to deliver a quick and easy-to-use solution to generate HTML documentation from markdown files in your repository (ideally without any configuration).
It is intended for simple use cases where solutions like JSDoc would be overkill. It is not meant to compete with more complex products and therefore the feature set and configuration options will be kept to a minimum.
docsMD uses marked, handlebars and highlight.js internally.
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent