@accordproject/markdown-cli
v0.17.2
Published
A framework for transforming markdown
Readme
Command Line
Install the @accordproject/markdown-cli npm package to access the Markdown Transform command line interface (CLI). After installation you can use the markus command and its sub-commands as described below.
To install the Markdown CLI:
npm install -g @accordproject/markdown-cliUsage
markus is a command line tool to debug and use markdown transformations.
markus <cmd> [args]
Commands:
markus transform transform between two formats
Options:
--version Show version number [boolean]
--verbose, -v [default: false]
--help Show help [boolean]markus transform
The markus transform command lets you transform between any two of the supported formats
markus transform
transform between two formats
Options:
--version Show version number [boolean]
--verbose, -v verbose output [boolean] [default: false]
--help Show help [boolean]
--input path to the input [string]
--from source format [string] [default: "markdown"]
--to target format [string] [default: "commonmark"]
--via intermediate formats [array] [default: []]
--roundtrip roundtrip transform [boolean] [default: false]
--output path to the output file [string]
--model array of concerto model files [array]
--template template grammar [string]
--contract contract template [boolean] [default: false]
--currentTime set current time [string] [default: null]
--plugin path to a parser plugin [string]
--sourcePos enable source position [boolean] [default: false]
--offline do not resolve external models [boolean] [default: false]Example
For example, you can use the transform command on the README.md file from the Hello World template:
markus transform --input README.mdreturns:
{
"$class": "[email protected]",
"xmlns": "http://commonmark.org/xml/1.0",
"nodes": [
{
"$class": "[email protected]",
"level": "1",
"nodes": [
{
"$class": "[email protected]",
"text": "Hello World"
}
]
},
{
"$class": "[email protected]",
"nodes": [
{
"$class": "[email protected]",
"text": "This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string "
},
{
"$class": "[email protected]",
"text": "Hello"
},
{
"$class": "[email protected]",
"text": " prepended to text that is passed in the request."
}
]
}
]
}--from and --to options
You can indicate the source and target formats using the --from and --to options. For instance, the following transforms from markdown to html:
markus transform --from markdown --to htmlreturns:
<html>
<body>
<div class="document">
<h1>Hello World</h1>
<p>This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string <code>Hello</code> prepended to text that is passed in the request.</p>
</div>
</body>
</html>--via option
When there are several paths between two formats, you can indicate an intermediate format using the --via option. The following transforms from markdown to html via ciceromark:
markus transform --from markdown --via ciceromark --to htmlreturns:
<html>
<body>
<div class="document">
<h1>Hello World</h1>
<p>This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string <code>Hello</code> prepended to text that is passed in the request.</p>
</div>
</body>
</html>--roundtrip option
When the transforms allow, you can roundtrip between two formats, i.e., transform from a source to a target format and back to the source target. For instance, the following transform from markdown to ciceromark and back to markdown:
markus transform --from markdown --to ciceromark --input README.md --roundtripreturns:
Hello World
====
This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string `Hello` prepended to text that is passed in the request.Roundtripping might result in small changes in the source markdown, but should always be semantically equivalent. In the above example the source ATX heading # Hello World has been transformed into a Setext heading equivalent.
--model --contract options
When handling TemplateMark, one has to provide a model using the --model option and whether the template is a clause (default) or a contract (using the --contract option).
For instance the following converts markdown with the template extension to a TemplateMark document object model:
markus transform --from markdown_template --to templatemark --model model/model.cto --input text/grammar.tem.mdreturns:
{
"$class": "[email protected]",
"xmlns": "http://commonmark.org/xml/1.0",
"nodes": [
{
"$class": "[email protected]",
"name": "top",
"elementType": "org.accordproject.helloworld.HelloWorldClause",
"nodes": [
{
"$class": "[email protected]",
"nodes": [
{
"$class": "[email protected]",
"text": "Name of the person to greet: "
},
{
"$class": "[email protected]",
"name": "name",
"elementType": "String"
},
{
"$class": "[email protected]",
"text": "."
},
{
"$class": "[email protected]"
},
{
"$class": "[email protected]",
"text": "Thank you!"
}
]
}
]
}
]
}--template option
Parsing or drafting contract text using a template can be done using the --template option, usually with the corresponding --model option to indicate the template model.
For instance, the following parses a markdown with CiceroMark extension to get the correspond contract data:
markus transform --from markdown_cicero --to data --template text/grammar.tem.md --model model/model.cto --input text/sample.md returns:
{
"$class": "org.accordproject.helloworld.HelloWorldClause",
"name": "Fred Blogs",
"clauseId": "fc345528-2604-420c-9e02-8d85e03cb65b"
}