letdoc

    0.2.5 • Public • Published

    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 diagram 1

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

    Mermaid diagram 2

    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

    Chartjs chart 1

    Dependencies

    npm install

    Install

    npm i letdoc

    DownloadsWeekly Downloads

    11

    Version

    0.2.5

    License

    MIT

    Unpacked Size

    2.39 MB

    Total Files

    32

    Last publish

    Collaborators

    • blackcrow33