noop(); pop(); map();

    raml-to-markdown

    1.2.6 • Public • Published

    raml-to-markdown

    Coverage Status

    RAML to Markdown is a simple tool to create documentations out of RAML service definitions. Its output is template based to enable developers to change the output structure, style or even the output type e.g. by creating html templates.

    This module provides a comfortable APIs and a full featured command line client.

    Install

    npm install -g raml-to-markdown
    

    Command-line interface

    After installing you may use the command-line interface (CLI) on the terminal of your computer. The command is named "raml2md".

    raml2md --help
    
    Usage: raml2md [options] [path]
    
    Options:
    
      -h, --help                 output usage information
      -r, --recursive            Scan <path> recursively.
      -t, --template <template>  Template file to use for output generation.
      -o, --output-type <type>   Where to put the output. Possible values: stdout, file, file-per-resource.
      -f, --output-file <file>   File to output results to if output type is file.
      -p, --output-path <path>   Path to output results to if output type is file-per-resource.
      -c, --config <file>        Path to a JSON config file to use.
      --output-ext <extension>   File extension of result files if output type is file-per-resource.
      --file-filter <regexp>     RegExp for filtering files.
    

    Config file

    The config file represents all configuration options available to run the tool from command line. These are almost the same options as shown in the DefaultConfig section of the API description. In order to use the module programmatically, you will have to use the DefaultConfig settings instead.

    {
        "input": {
            "paths": [],
            "recursive": false,
            "fileFilter": "\\.raml$",
            "templateFile": "./templates/index.njk"
        },
        "output": {
            "type": "StdOut",
            "file": {
                "splitting": "AllInOne",
                "path": null,
                "extension": ".md"
            }
        }
    }

    API

    You might also want to use the API of this tool as a library. The library provides two methods to call. A parse() and a render() method.

    The parse() method returns an array with objects containing all information extracted from the source. Each array index represents one source file parsed.

    The render() method does the same but outputs a processed template depending on the input and output settings of the passed configuration object.

    Both methods return a Promise object. Depending on the configuration settings, the promise contains the rendered output or undefined.

    const raml2md = require('raml-to-markdown');
     
    raml2md.parse({ input : { paths : [ '...' ] } }).then(console.log);
    raml2md.render({ input : { paths : [ '...' ] } }).then(console.log);

    For configuration options please have a look at the DefaultConfig section.

    Templating

    This module uses Nunjucks in order to structure the parsed RAML. By changing the provided or creating a new template, you would be able to create almost every formatted text output.

    DefaultConfig

    {
       input : {
           paths : [ ],
           recursive : false,
           fileFilter : new RegExp('\.raml$'),
           templateFile : './templates/index.njk',
           contentFilter : null
       },
       output : {
           type : this.OutputType.ReturnOnly,
           file : {
               splitting : this.FileSplitting.AllInOne,
               path : null,
               extension : '.md'
           },
           contentFilter : item => item.replace(/\n{3,}/g, "\n\n")
       }
    }

    Install

    npm i raml-to-markdown

    DownloadsWeekly Downloads

    427

    Version

    1.2.6

    License

    MIT

    Unpacked Size

    22.3 kB

    Total Files

    12

    Last publish

    Collaborators

    • kwierchris