Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(README): outdated MD-CLI documentation - #363 #366

Merged
merged 1 commit into from
Apr 2, 2021
Merged

docs(README): outdated MD-CLI documentation - #363 #366

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 193 additions & 52 deletions packages/markdown-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,238 @@
# Markdown Transform CLI

Command line tool to debug and use markdown transformations.
# Command Line

## Installation
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:

```bash
npm install -g @accordproject/markdown-cli
```

## Usage

The command-line is called `markus` and offers the following commands:
`markus` is a command line tool to debug and use markdown transformations.

```
```md
markus <cmd> [args]

Commands:
markus parse parse and transform a sample markdown, pdf or docx file
markus draft create markdown text from data
markus normalize normalize a sample markdown (parse & redraft)
markus transform transform between two formats

Options:
--version Show version number [boolean]
--verbose, -v [default: false]
--help Show help [boolean]
```

### Parse from Markdown
## `markus transform`

The `parse` command lets you parse markdown and create a document object model from it.
The `markus transform` command lets you transform between any two of the supported formats

```
markus parse
```md
markus transform

parse and transform a sample markdown
transform between two formats

Options:
--version Show version number [boolean]
--verbose, -v verbose output [boolean] [default: false]
--help Show help [boolean]
--sample path to the markdown text, pdf, docx [string]
--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]
--cicero further transform to CiceroMark [boolean] [default: false]
--slate further transform to Slate DOM [boolean] [default: false]
--html further transform to HTML [boolean] [default: false]
--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]
```

### Generate markdown from data
### Example

The `draft` command lets you take a document object model and generate markdown text from it.
For example, you can use the `transform` command on the `README.md` file from the [Hello World](https://github.com/accordproject/cicero-template-library/blob/master/src/helloworld) template:

```bash
markus transform --input README.md
```
markus draft

create markdown text from data
returns:

```json
{
"$class": "org.accordproject.commonmark.Document",
"xmlns": "http://commonmark.org/xml/1.0",
"nodes": [
{
"$class": "org.accordproject.commonmark.Heading",
"level": "1",
"nodes": [
{
"$class": "org.accordproject.commonmark.Text",
"text": "Hello World"
}
]
},
{
"$class": "org.accordproject.commonmark.Paragraph",
"nodes": [
{
"$class": "org.accordproject.commonmark.Text",
"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": "org.accordproject.commonmark.Code",
"text": "Hello"
},
{
"$class": "org.accordproject.commonmark.Text",
"text": " prepended to text that is passed in the request."
}
]
}
]
}
```

Options:
--version Show version number [boolean]
--verbose, -v verbose output [boolean] [default: false]
--help Show help [boolean]
--data path to the data [string]
--output path to the output file [string]
--cicero input data is a CiceroMark DOM [boolean] [default: false]
--slate input data is a Slate DOM [boolean] [default: false]
--html input data is HTML [boolean] [default: false]
--noWrap do not wrap CiceroMark variables as XML tags
[boolean] [default: false]
--noIndex do not index ordered lists [boolean] [default: false]
### `--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`:

```bash
markus transform --from markdown --to html
```

returns:

```md
<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>
```

### Normalize the markdown
### `--via` option

The `normalize` command lets you parse markdown and re-draft it from its document object model.
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* `slate`:

```bash
markus transform --from markdown --via slate --to html
```
markus normalize

normalize a sample markdown (parse & redraft)
returns:

```md
<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>
```

Options:
--version Show version number [boolean]
--verbose, -v verbose output [boolean] [default: false]
--help Show help [boolean]
--sample path to the markdown text [string]
--output path to the output file [string]
--cicero further transform to CiceroMark [boolean] [default: false]
--slate further transform to Slate DOM [boolean] [default: false]
--html further transform to HTML [boolean] [default: false]
--noWrap do not wrap variables as XML tags [boolean] [default: false]
--noIndex do not index ordered lists [boolean] [default: false]
### `--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 `slate` and back to markdown:

```md
markus transform --from markdown --to slate --input README.md --roundtrip
```

## License <a name="license"></a>
Accord Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file. Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/.
returns:

© 2017-2019 Clause, Inc.
```bash
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](https://docs.accordproject.org/docs/markdown-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:

```bash
markus transform --from markdown_template --to templatemark --model model/model.cto --input text/grammar.tem.md
```

returns:

```json
{
"$class": "org.accordproject.commonmark.Document",
"xmlns": "http://commonmark.org/xml/1.0",
"nodes": [
{
"$class": "org.accordproject.templatemark.ClauseDefinition",
"name": "top",
"elementType": "org.accordproject.helloworld.HelloWorldClause",
"nodes": [
{
"$class": "org.accordproject.commonmark.Paragraph",
"nodes": [
{
"$class": "org.accordproject.commonmark.Text",
"text": "Name of the person to greet: "
},
{
"$class": "org.accordproject.templatemark.VariableDefinition",
"name": "name",
"elementType": "String"
},
{
"$class": "org.accordproject.commonmark.Text",
"text": "."
},
{
"$class": "org.accordproject.commonmark.Softbreak"
},
{
"$class": "org.accordproject.commonmark.Text",
"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:

```bash
markus transform --from markdown_cicero --to data --template text/grammar.tem.md --model model/model.cto --input text/sample.md
```

returns:

```json
{
"$class": "org.accordproject.helloworld.HelloWorldClause",
"name": "Fred Blogs",
"clauseId": "fc345528-2604-420c-9e02-8d85e03cb65b"
}
```