Introduction

Welcome to Documentor documentation

A super intuitive doc generator from Markdown files

Documentor was made to create a documentation from simple flat markdown files.

The goal of the project is

• To have an easy way to do it
• To embed everything (style, script, images) in a single html file
• To be able to read the documentation without javascript
• To have a simple search engine (if javascript is enabled)
• To be easily customizable

Installation

Install Documentor globally to have the documentor command in your terminal.

Please make sure that you have node version 7.6.0+.

# for npm users
npm install -g documentor
# for yarn users
yarn global add documentor

Usage

Express Usage

• Run documentor init to initialize your documentation
• Run documentor ./yourFolder -o output.html to render your documentation

For more Information

• Command Line Usage
• Markdown Files

Command Line

• -i, --input: Input folder (optional flag)
• -o, --output: Write in file
• -t, --to: Output format
• -c, --config: Configuration file
• -w, --watch: Watch docs files with partial generation
• -q, --quite: Do not output any message
• -v, --verbose: Increase the verbosity
• --var, --variable: Set or override config variable(s)
• -h, --help: Show help

Examples

Generate project.html from ./docs folder

documentor ./docs -o out.html

Output html to STDOUT from ./docs folder and read the configuration file conf.yml

documentor docs -c conf.yml

Generate "out.html" with a custom name and footer

documentor ./docs -o out.html --var.name "My Project" --var.footer "(c) Project 1.0"

Watch the "docs" folder and regenerate "out.html" on change

documentor docs -o out.html -w

Markdown Files

File Structure

Documentor will list all markdown file with the .md or .markdown extension to create pages of the documentation.

To hide a file from the listing, you can prefix the file with an underscore (eg. _hideMe.md).

The pages are sorted alphabetically. To sort your pages manually you can prefix a number followed by an underscore (eg. 0_Introduction, 1_HowToUse, etc.).

It is possible to have sub pages by creating sub files in a folder. The folder name will be seen as an empty page. To add content to this page, you can name your file index.md.

The title of the page is generated from the file name. The file name will be decamelized (eg. MySuperTitle will become My Super Title).

Example

.
└── docs
    ├── _config.yml        # Optional configuration
    ├── 0_Introduction.md
    ├── _todo.md           # This will not be listed in the documentation
    └── Basics
        ├── index.md       # This will be seen as the "Basics" page
        ├── 0_Action.md
        └── 1_Reaction.md

Markdown Files

Markdown support the CommonMark spec and table (GFM).

Header

An optional header can be specified to override predefined variables.

The header must be the on top on the files, separated by ---, in a yaml format.

Available variables

Variable	Default	Description
title	File name, decamelized with caps	Set a specific title
slug	File name	To define the slug in the url (after the #)

Example

---
title: Introduction
slug: intro
---

Lorem ipsum...

Configuration

By default, Documentor will read _config.yml in the root folder of the documentation but you can pass -c or --config to use your own config path (see the Command Line Usage for more information).

Options

• name – Name of the project. It will be the main title for the html page.
• version – Version of the project.
• homepageUrl – Homepage of the project
• logo – Main logo of the project.
• icon – Icon of the project, will typically be used for the favicon of the html page.
• footer – The content of the footer.
• template – By default Documentor uses the alchemy template. To use a custom template path, start with ./ for a relative path or / for an absolute path.
  • Example – template: ./mytemplate
• htmlHeader – List of html element to add in the header
• htmlBody – List of html element to add in the body
• markdown-it – You can specified some options to the parser. Please read Markdown-it doc for more info.

All fields are optionals.

Example of a Configuration File

name: Documentor
version: 1.0.0
logo: _assets/logo.png
icon: _assets/icon.png

External Library

External libraries can be loaded easily from the configuration (or a custom template), here is some examples using CDNs.

Syntax Highlighting

You can add code coloration for code blocks with javascript libraries.

Use the configuration htmlHeader to add the CSS in the header and htmlBody to run the javascript in the body.

Example with Highlightjs

For example with highlightjs you can simply add the css and javascript from their CDN.

# In `_config.yml`
htmlHeader:
  - <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.0.3/styles/default.min.css">
htmlBody:
  - <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.0.3/highlight.min.js"></script>
  - <script>hljs.initHighlightingOnLoad();</script>

Math Support

There is many libraries to add math support, like KaTeX and MathJax.

Example with KaTeX

Follow the documentation and add the right css/javascript from their CDN.

With the basic configuration, you will be able to type latex formulas between $$.

Example: $$c = \\pm\\sqrt{a^2 + b^2}$$

# In `_config.yml`
htmlHeader:
  - <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
htmlBody:
  - <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>
  - <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"
        onload="renderMathInElement(document.body);"></script>

Note: The library is not loaded in this documentation

Diagrams Support

Example with Mermaid

You can use Mermaid to create diagrams from text, with this example you need to add the "mermaid" language on code blocks.

```mermaid
graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
``​`

# In `_config.yml`
htmlBody:
  - <script src="https://unpkg.com/mermaid@8.5/dist/mermaid.min.js"></script>
  - <script>mermaid.init({startOnLoad:true}, '.language-mermaid');</script>

Note: The library is not loaded in this documentation

Customization

You can customize the style or structure by creating your own template.

documentor ./docs -o out.html --var.template "./myTemplate"

A template is composed of html, javascript and css. The structure of the template needs to be the following:

.
└── myTemplate
    ├── base.html
    ├── main.js
    └── style.css

The javascript and css files are optional. To begin, check how the build-in template is made in the templates/alchemy folder.

Html

The html use Handlebar as a template, Handlebars is largely compatible with Mustache templates.

Style (css)

Documentor uses Postcss with cssnext. You can thus uses the features of cssnext.

Javascript

Javascript is transpiled with Babel to ECMAScript 5. You can use ECMAScript 6, modules, fat arrow etc.