Necessitates Proper Modularity

    coffeekraken-docblock-json-to-markdown

    1.0.4 • Public • Published

    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

    1. Install
    2. Get Started
    3. Documentation
    4. Contribute
    5. Who are Coffeekraken?
    6. 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:

    1. Share the love ❤️
    2. Declare issues
    3. Fix issues
    4. Add features
    5. Build web component

    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.

    More on who we are

    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...

    Install

    npm i coffeekraken-docblock-json-to-markdown

    DownloadsWeekly Downloads

    1

    Version

    1.0.4

    License

    MIT

    Unpacked Size

    248 kB

    Total Files

    112

    Last publish

    Collaborators

    • olivierbossel