Documentation by markdown with customized layout

Technical documentation should be easily ready by a user. Layouting the content of a document takes lots of time in Windows Word. Especially, Technical document, the coding block is hard to read. Markdown has been widely adopted for the documnetation but it needs a massage in order to present to your client. As the result, HTML should be a good option as a output format of a document. Different format of document can be generated by browser. Printing as PDF or saving the whole page as an image file.

This simple project is designed to work with Mermaid and Chartjs. If the markdown can express a diagram in words and or using Javascript code to generate a chart will be helpful to me for writing a document to a client.

Install

npm install -g letdoc

Usage

letdoc example.md
# or
letdoc example.md myexample.html

An example content in example.md

[comment]: # (title : <Your Project Title>)
[comment]: # (author: <Your Author Version>)
[comment]: # (version: <Your Document Version>)
[comment]: # (company: <Your Company Name>)
[comment]: # (client: <Your Client Name>)

# My Project Title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse nisi mauris, mollis in leo ut, congue vulputate enim. Nulla interdum posuere orci in volutpat. Nulla fringilla erat leo, id sollicitudin velit sollicitudin non. Mauris condimentum nisi id lorem dignissim interdum. Curabitur lacinia vestibulum pharetra. Mauris at nisi eu nibh aliquet elementum et in lectus. Nunc viverra consectetur purus, sit amet fringilla est porta ut. Nam sem risus, rutrum ut pharetra eu, ornare non metus. Phasellus quis sodales metus. Nunc ornare vestibulum lectus, sed malesuada dui faucibus quis. Donec vulputate nibh a tortor pellentesque consequat. Vivamus faucibus nulla id varius imperdiet.

Customized Template

Design your own template in html format and put it in the templates folder of project root and run as following:

letdoc --template mytemplate example.md
# or
letdoc -t mytemplate example.md

Set logo in default template

letdoc --logo ./logo.png example.md
# or
letdoc -l ./logo.png example.md

PNG or PDF Formats

You can generate a full page png / pdf instead of html file by adding an option with the command:

Sample page image

letdoc -f png example.md example.png
# or
letdoc -f pdf example.md example.pdf

Mermaid Examples

Writing a code block with a syntax keyword mermaid to let the generator knows which code block will be converted into diagram/chart. Besides, the svg will be optimized by SVGO to minize the file size of the output document.

```mermaid
sequenceDiagram
    autonumber
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

The mermaid diagram will generate as a svg and embbed in the output html file just like the image is shown below:

```mermaid
pie title NETFLIX
  "Time spent looking for movie" : 90
  "Time spent watching it" : 10
```

ChartJS

Adding keyword chartjs behinds the syntax name to let the generator knows which code block will be used to generate a svg chart in the output document.

Generating Chartjs diagram by using code block like belows:

```js chartjs
var data = {
  labels: ['Red', 'Blue', 'Yellow', 'Green', 'Purple', 'Orange'],
  datasets: [
    {
      label: '# of Votes',
      data: [12, 19, 3, 5, 2, 3],
      backgroundColor: [
        'rgba(255, 99, 132, 0.2)',
        'rgba(54, 162, 235, 0.2)',
        'rgba(255, 206, 86, 0.2)',
        'rgba(75, 192, 192, 0.2)',
        'rgba(153, 102, 255, 0.2)',
        'rgba(255, 159, 64, 0.2)',
      ],
      borderColor: [
        'rgba(255, 99, 132, 1)',
        'rgba(54, 162, 235, 1)',
        'rgba(255, 206, 86, 1)',
        'rgba(75, 192, 192, 1)',
        'rgba(153, 102, 255, 1)',
        'rgba(255, 159, 64, 1)',
      ],
      borderWidth: 1,
    },
  ],
};

new Chart(ctx, {
  type: 'bar',
  data: data,
  options: {
    scales: {
      yAxes: [
        {
          ticks: {
            beginAtZero: true,
          },
        },
      ],
    },
  },
})
```

Noted: You can write a simple logic to generate a dynamic dataset for chartjs

Dependencies

npm install