Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/opuscapita/raml-to-markdown
Create Markdown documentaion out of RAML files.
https://github.com/opuscapita/raml-to-markdown
andariel bnp library util
Last synced: about 1 month ago
JSON representation
Create Markdown documentaion out of RAML files.
- Host: GitHub
- URL: https://github.com/opuscapita/raml-to-markdown
- Owner: OpusCapita
- License: mit
- Created: 2017-03-15T16:09:20.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-11-02T03:14:09.000Z (about 5 years ago)
- Last Synced: 2024-09-08T15:44:47.801Z (4 months ago)
- Topics: andariel, bnp, library, util
- Language: JavaScript
- Homepage:
- Size: 216 KB
- Stars: 3
- Watchers: 17
- Forks: 5
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# raml-to-markdown
[](https://coveralls.io/github/OpusCapita/raml-to-markdown)
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](#templating).
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 recursively.
-t, --template Template file to use for output generation.
-o, --output-type Where to put the output. Possible values: stdout, file, file-per-resource.
-f, --output-file File to output results to if output type is file.
-p, --output-path Path to output results to if output type is file-per-resource.
-c, --config Path to a JSON config file to use.
--output-ext File extension of result files if output type is file-per-resource.
--file-filter 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](#defaultconfig) section of the API description. In order to use the module programmatically, you will have to use the [DefaultConfig](#defaultconfig) settings instead.
```JS
{
"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.
```JS
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](#defaultconfig) section.
#### Templating
This module uses [Nunjucks](https://www.npmjs.com/package/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
```JS
{
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")
}
}
```