command-line-publish/README.md

Convert `command-line-usage` JSON or JavaScript ESM into HTML or SVG files

# command-line-publish

Tool to convert [`command-line-args`](https://www.npmjs.com/package/command-line-args)/[`command-line-usage`](https://github.com/75lb/command-line-usage/)
JSON arrays to SVG or HTML.

## Install

```shell
npm install -D command-line-publish
```

## CLI Usage

```shell
command-line-publish <args>
```

or:

```shell
clp --format=html --config="jsWithSectionsExport.js" "cli.html"
clp --format=svg --config="jsonWithSectionsProperty.json" "cli.svg"
```

And here is the documentation generated by our use of `command-line-publish`
on itself.

First as HTML:

- [cli.html](https://brettz9.github.io/command-line-publish/cli.html)

And then as embeddable SVG (not copy-pasteable on the README, but it is if
you click the image or visit the file
[directly](https://brettz9.github.io/command-line-publish/cli.svg)):

![cli.svg](https://brettz9.github.io/command-line-publish/cli.svg)

After using the commands to generate, you can:

- Link to the HTML, e.g., as we did above: `[cli.html](https://brettz9.github.io/command-line-publish/cli.html)`
- Embed the SVG, e.g., as we did above: `![cli.svg](https://brettz9.github.io/command-line-publish/cli.svg)` (If you are not on Github Pages, you may, in the case of SVG, also use the form: `![cli.svg](https://raw.githubusercontent.com/brettz9/command-line-publish/master/cli.svg?sanitize=true)` (Applying for HTML will only show the raw source.))

Note that we have configured this repository's `master` branch to have its
contents served from Github Pages.

## Programmatic usage

```js
import {html, svg} from 'command-line-publish';

// This JavaScript (or JSON) file must export a `sections` property,
//  and for easier reusability, it is recommended that ths same file
//  define a `definitions` property for use by `command-line-args`
import {sections} from './path/to/config-file.js';

// The options objects are optional
svg(sections, {target: 'cli.svg', ansiToSvgOptions: {}});
html(sections, {target: 'cli.html', ansiToHtmlOptions: {}});
```

Here is a sampling of our own config file:

```js
import {readFile} from 'fs/promises';

const pkg = JSON.parse(
  await readFile(new URL('../package.json', import.meta.url))
);

const optionDefinitions = [
  {
    name: 'target', alias: 't', type: String, defaultOption: true,
    description: 'The file path target to which to write the result',
    typeLabel: '{underline file-path}'
  },
  // ... snipped
  {
    name: 'help', alias: 'h', type: Boolean,
    description: 'Display this help guide'
  }
];

const cliSections = [
  {
    // We're now actually letting `command-line-basics auto-generate the
    //  `header` now
    header: pkg.name,
    // Add italics: `{italic textToItalicize}`
    content: pkg.description +
      '\n\n{italic clp -c="configPath" [--format=svg|html] target}'
  },
  {
    // We're now actually letting `command-line-basics auto-generate the
    //  `header` now
    header: 'Options',
    optionList: optionDefinitions
  }
];

export {optionDefinitions as definitions, cliSections as sections};
```

## See also

- [command-line-args](https://github.com/75lb/command-line-args)
- [command-line-usage](https://github.com/75lb/command-line-usage/)
- [command-line-basics](https://github.com/brettz9/command-line-basics)