A plugin for doxie.
Join rendered docs and inject them into your readme.

Installation

doxie --inject is a plugin for the command-line tool doxie. dox produces compatible data from jsDoc comments. Install all three if you haven’t already:

$ npm install --global dox doxie doxie.inject

Usage

1. Write a readme

…or some other document in Markdown or HTML. Put the markers <!-- @doxie.inject start --> and <!-- @doxie.inject end --> somewhere in it.

2. Profit!

Render your docs with doxie – here we use doxie --render for that. Then --inject them into your readme.

$ dox | doxie --render --inject

We’ll join your docs into one string and replace all content between the markers with that string.

3. Options!

You can set things up with options:

--inject( <option> <argument>)*

For example:

$ doxie --render \
$   --inject into 'My docs.md' as public

Read on!

Options

Apart from the default markers you can have named markers. This way you can inject different docs at different places.

Put them in your readme: <!-- @doxie.inject start my-marker --> and <!-- @doxie.inject end my-marker -->.

Then inject your docs:

$ doxie --inject as my-marker

By default we’ll inject your docs into README.md, Readme.md, or readme.md in the current working directory. But if you want another target, no problem:

$ doxie --inject into ./documentation/my-docs.html

Programmatic usage

You can use doxie.inject directly with doxie-core. Install both if you haven’t already:

$ npm install doxie-core doxie.inject

Use it like this:

Parameters (properties of an object):

• input
  type: String (or cast to String) | required
  The content of a readme – or another Markdown / HTML document.

• as
  type: String or null (or cast to String) | optional | default: null
  Same as --inject as <marker name>.

Returned value:

• plugin
  type: Function
  Pass this to doxie-core.

Returned properties:

• ['doxie.inject'].output
  type: String
  The resulting content of the readme – with your docs injected.

• …
  Other properties required by doxie-core.

Example:

const doxie = require('doxie-core');
const render = require('doxie.render');
const inject = require('doxie.inject');

doxie([
  render(require('./.doxie.render.js')),
  inject({
    input:
`#  My readme  #

##  Usage  ##
<!-- @doxie.input start usage -->
(this will be replaced)
<!-- @doxie.input end usage -->

##  License: MIT  ##
`,
    as: 'usage',
  }),
])([/* my docs’ data */]);
//» {
//    'doxie.inject': {output: "
//      #  My readme  #
//      
//      ##  Usage  ##
//      <!-- @doxie.input start usage -->
//      
//      ###  myFancyFunction(a, b, c)  ###
//      
//      Parameters:
//      
//      * a
//      * b
//      * c
//      
//      Return value:
//      
//      * d
//      <!-- @doxie.input end usage -->
//      
//      ##  License: MIT  ##
//    "},
//    …
//  }

License

MIT © Studio B12 GmbH