Nicaragua's Pet Mice

    docketjs

    1.0.7 • Public • Published

    Docket Js

    Version Build Status Coverage Status License

    DocketJs is a battery included (Markdown/AsciiDoc) to HTML converter for Node.js. It has everything you need to successfully convert a bunch of markdown/asciidoc files to HTML and generate toc with a menu file.

    Features

    1. Support GFM Syntax.
    2. Parses Front matter.
    3. Generates a menu JSON file to be used for showing up the menu in HTML.
    4. Generates TOC for each markdown document.
    5. Markdown readers to read files from Github and local disk.
    6. AsciiDoc readers to read files from Github and local disk.
    7. Writer to write compiled HTML files to the disk.

    Basic Example (Markdown)

    const Docket = require('docketjs')
    const path = require('path')
    const reader = new Docket.FSReader(path.join(__dirname, 'docs/markdown'))
    const menu = new Docket.Menu(path.join(__dirname, 'docs/menu.json'))
    const writer = new Docket.FSWriter(path.join(__dirname, 'docs/html'))
    const markdown = new Docket.Markdown()
     
    new Docket.Manager(reader, markdown, writer, menu)
      .convert()
      .then(() => {
        console.log('All went good')
      })
      .catch(console.error)

    Basic Example (AsciiDoc)

    const Docket = require('docketjs')
    const path = require('path')
    const reader = new Docket.FSReader(path.join(__dirname, 'docs/asciidoc'))
    const menu = new Docket.Menu(path.join(__dirname, 'docs/menu.json'))
    const writer = new Docket.FSWriter(path.join(__dirname, 'docs/html'))
    const adoc = new Docket.AsciiDoc()
     
    new Docket.Manager(reader, adoc, writer, menu)
      .convert()
      .then(() => {
        console.log('All went good')
      })
      .catch(console.error)

    Listening For Events

    Also you can listen for different events to track the progress of converting markdown/asciidoc documents to HTML.

    const docket = new Docket.Manager(reader, markdown, writer, menu)
     
    docket.on('converting', (docPath) => {
      console.log(`converting ${docPath}`)
    })
    docket.on('converted', (docPath) => {
      console.log(`converted ${docPath}`)
    })
    docket.on('writing', (doc) => {
      console.log(`writing ${doc.meta.permalink}`)
    })
     
    docket
      .convert()
      .then(() => {
        console.log('All went good')
      })
      .catch(console.error)

    Standards For YAML Front Matter

    YAML front matter helps you in defining setting for a markdown document. DocketJs makes use of it to build the menu tree for you and you are required to follow some rules when defining front matter.

    ---
    title: Adonis 101
    permalink: adonis-101
    weight: 0
    categories:
      - basics
    ---
     
    And here goes your markdown document
    key Required Default Value Description
    title Yes null Document title
    permalink Yes null Document url and html file name
    weight No 0 Weight defines the position of a document inside the menu tree
    categories No ['root'] Array of categories a doc belongs to

    Components

    DocketJs is divided into multiple classes to keep all the concerns seperated. You can also add your own implementations of these components.

    Readers

    Readers are used to read markdown files and return them as an array. DocketJs has two in-built readers:

    1. Read files from a folder on your computer.
    2. Read files from Github using Github v3 API.

    Markdown Parser

    Markdown parser makes use of marked to parse the markdown documents to HTML and at the same time and parses a lot of other information for your markdown documents.

    1. Parses YAML front matter using gray matter.
    2. Auto generate TOC for each markdown document.
    3. Parse markdown to HTML with GFM support.

    AsciiDoc Parser

    AsciiDoc parser makes use of asciidoctor.js to parse the asciidoc documents to HTML.

    Menu Builder

    Menu builder generates a menu tree of all the documents. Menu builder is dependent upon YAML front matter to read the permalink, title and weight of the document.

    weight defines the position of a document link inside a the menu. It is really helpful to keep menu items organized.

    Writers

    Writers are opposite of Readers and they write all the Markdown to HTML converted documents back to local folder.

    Menu Service

    Menu service can also be used to load a file from disk and then perform operations like, get tree to display in HTML, or get a document meta for a given permalink

    const Menu = require('docketjs').Menu
    const path = require('path')
    const menu = new Menu()
     
    menu.load('menu.json') // loading previously saved file
     
    console.log(menu.tree())

    tree([categories])

    Returns menu tree with all childs sorted according to their weight. Optionally you can also pass an array of categories to be used for sorting categories.

    menu.load('menu.json')
    const tree = menu.tree()

    getChild(permalink)

    Returns child for a given permalink

    menu.load('menu.json')
    const routing = menu.getChild('routing')
    /**
      {
        title: 'Routing',
        permalink: 'routing',
        weight: 0
      }
     */

    getPrevious(tree, peramlink)

    Returns previous child for a given permalink. It is important to pass a sorted tree to this method, since the previous item inside the unsorted tree can be different from the sorted tree.

    menu.load('menu.json')
    const tree = menu.tree()
    const previousChild = menu.getPreviousChild(tree, 'routing')

    getNextChild(tree, peramlink)

    Returns next child for a given permalink. It is important to pass a sorted tree to this method, since the next item inside the unsorted tree can be different from the sorted tree.

    menu.load('menu.json')
    const tree = menu.tree()
    const nextChild = menu.getNextChild(tree, 'routing')

    Github Reader

    Just like FSReader you can make use of GithubReader to read the documents from a Github repo.

    const reader = new Docket.GithubReader('adonisjs/docs', 'master', '3.0')

    Next you need to pass this reader to the Docket Manager and it will fetch the docs for you.

    Optionally it can make use of Github Token to make an authenticated request, which has better rate limits.

    process.env.GH_TOKEN = '<your github token>'
    const reader = new Docket.GithubReader('adonisjs/docs', 'master', '3.0')

    Keywords

    none

    Install

    npm i docketjs

    DownloadsWeekly Downloads

    3

    Version

    1.0.7

    License

    MIT

    Last publish

    Collaborators

    • virk