Coffeekraken Docblock JSON to Markdown

This package gives you the ability transform with ease a coffeekraken-docblock-parser resulting JSON into a beautiful markdown file.

Table of content

Install
Get Started
Documentation
Contribute
Who are Coffeekraken?
Licence

Install

npm install git+ssh://git@github.com:Coffeekraken/docblock-json-to-markdown.git#release/0.0.1 --save-dev

Get Started

First, require the package in your javascript node file like so:

const docblockJSONToMarkdown = require('coffeekraken-docblock-json-to-markdown');
// use the package like so:
const markdown = docblockJSONToMarkdown(config).jsonToMarkdown(myCoolJSON);

Documentation

Config

Here's the configuration object that you can hook as needed:

{
  language : 'js', // Specify the language that is being processed like "js, scss, etc..."
  tags : {
    // all the tags render functions
    author : (author) => {
      return `- Author : ${author.name}`
    },
    // etc...
  },
  templates : {
    // all the templates render functions
    default : __defaultTemplate,
    // etc...
  },
  types : {
    // all the types URL for each languages like so:
    js : {
      HTMLElement : 'https://developer.mozilla.org/fr/docs/Web/API/HTMLElement',
      // etc...
      },
    scss : {
      // ...
    }
  }
}

Types

In the config object, you will find the "types" property. This property represent an object by language that simply map a type with a URL where you can find more info on this type.

Here's the available out of the box types:

{
  types : {
    js : {
      HTMLElement : 'https://developer.mozilla.org/fr/docs/Web/API/HTMLElement',
      HTMLLinkElement : 'https://developer.mozilla.org/fr/docs/Web/API/HTMLLinkElement',
      String : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/String',
      Array : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Array',
      Object : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Object',
      Function : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Function',
      Boolean : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Boolean',
      Date : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Date',
      Error : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Error',
      JSON : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/JSON',
      Map : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Map',
      Math : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Math',
      NaN : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/NaN',
      Number : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Number',
      Promise : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise',
      Proxy : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Proxy',
      RegExp : 'https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/RegExp'
    },
    scss : {
      List : 'http://www.sass-lang.com/documentation/file.SASS_REFERENCE.html#lists',
      String : 'http://www.sass-lang.com/documentation/file.SASS_REFERENCE.html#sass-script-strings',
      Map : 'http://www.sass-lang.com/documentation/file.SASS_REFERENCE.html#maps',
      Color : 'http://www.sass-lang.com/documentation/file.SASS_REFERENCE.html#colors',
      Function : 'http://www.sass-lang.com/documentation/file.SASS_REFERENCE.html#functions',
      Mixin : 'http://www.sass-lang.com/documentation/file.SASS_REFERENCE.html#mixins'
    },
    php : {
      String: 'http://php.net/manual/en/language.types.string.php',
      Boolean: 'http://php.net/manual/en/language.types.boolean.php',
      Integer: 'http://php.net/manual/en/language.types.integer.php',
      Float: 'http://php.net/manual/en/language.types.float.php',
      Double: 'http://php.net/manual/en/language.types.float.php',
      Array: 'http://php.net/manual/en/language.types.array.php',
      Object: 'http://php.net/manual/en/language.types.object.php',
      Callable: 'http://php.net/manual/en/language.types.callable.php',
      Resource: 'http://php.net/manual/en/language.types.resource.php',
      NULL: 'http://php.net/manual/en/language.types.null.php',
      Mixed: 'http://php.net/manual/en/language.pseudo-types.php#language.types.mixed',
      Number: 'http://php.net/manual/en/language.pseudo-types.php#language.types.number',
      Callback: 'http://php.net/manual/en/language.pseudo-types.php#language.types.callback'
    }
  }
}

Add/Override a tag display

You can through the config add or override how a specific tag will be printed out in your final markdown file. Here's how:

const docblockJSONToMarkdown = require('coffeekraken-docblock-json-to-markdown');
// make a custom config
const config = {
  tags : {
    example : (exampleData) => {
      // make your own display
      return `
        ### Example
        \`\`\`${exampleData.language}
        ${exampleData.body}
        \`\`\`
      `;
    },
    myCoolTag : (tagData) => {
      // return something for your new cool tag
    }
  }
};
// use the package like so:
const markdown = docblockJSONToMarkdown(config).jsonToMarkdown(myCoolJSON);

Custom templates

Templates are the backbone of the outputed markdown file. It describe which docblock will be displayed in which order, group, etc... Here's the default template:

export default function defaultTemplate(data) {
  return [
    this.renderBlocks(data.filter((block, index) => {
      return index === 0 && block.name && ! block.private && ! block.protected;
    }), {
      title : '@[0].name',
      titleLevelAdd : 1,
      doNotRender : ['name']
    }),
    this.renderBlocks(data.filter((block) => {
      return block.constructor === true;
    }), {
      doNotRender : ['name'],
      title : 'Constructor'
    }),
    this.renderBlocks(data.filter((block) => {
      return ! block.event && block.styleguide !== undefined;
    }), {
      title : 'Examples',
      description : "Here's some usage examples."
    }),
    this.renderBlocks(data.filter((block) => {
      return ! block.event && (block.prop !== undefined || block.attribute !== undefined);
    }), {
      title : 'Attributes',
      description : "Here's the list of available attribute to set on the element."
    }),
    this.renderBlocks(data.filter((block) => {
      return ! block.event && block.setting !== undefined;
    }), {
      title : 'Settings',
      description : "Here's the list of available settings."
    }),
    this.renderBlocks(data.filter((block) => {
      return ! block.event && ! block.return && block.types !== undefined && ! block.private && ! block.protected;
    }), {
      title : 'Properties'
    }),
    this.renderBlocks(data.filter((block) => {
      return ! block.event && ! block.types && ! block.private && ! block.protected;
    }), {
      title : 'Methods'
    }),
    this.renderBlocks(data.filter((block) => {
      return block.event && ! block.private && ! block.protected;
    }), {
      title : 'Events'
    })
  ].join("\n");
}

Register/override a new template

You can register or override any template like so:

const docblockJSONToMarkdown = require('coffeekraken-docblock-json-to-markdown');
// make a custom config
const config = {
  templates : {
    jsx : (data) => {
      return [
        this.renderBlocks(data.filter((block) => {
          return block.constructor === true;
        }), {
          doNotRender : ['name'],
          title : 'Constructor'
        })
      ].join("\n");
    }
  }
};
// use the package like so:
const markdown = docblockJSONToMarkdown(config).jsonToMarkdown(myCoolJSON);

The template index has to be the language extension of the file processed.

Contribute

This is an open source project and will ever be! You are more that welcomed to contribute to his development and make it more awesome every day. To do so, you have several possibilities:

Who are Coffeekraken

We try to be some cool guys that build some cool tools to make our (and yours hopefully) every day life better.

License

The code is available under the MIT license. This mean that you can use, modify, or do whatever you want with it. This mean also that it is shipped to you for free, so don't be a hater and if you find some issues, etc... feel free to contribute instead of sharing your frustrations on social networks like an asshole...

Package detail