@bentley/ecjson2md

ecjson2md

Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.

ecjson2md is a CLI tool that takes an ECSchema JSON and path to referenced schemas and generates a Markdown file based on it at a specified location.

Change Log

Installation

---

Install globally (recommended)

npm install -g @bentley/ecjson2md

Install locally

npm install @bentley/ecjson2md

Usage

---

Generate a markdown file from ECSchema JSON via command line

ecjson2md -i <path to ECSchema JSON> -r <comma, semicolon, or space separated search dirs> -o <directory to output markdown>

Note: If no search directories are needed, you don't need to include the -r option Note: When using multiple search paths, enclose them in single quotes

Generate a markdown file from ECSChema JSON file programmatically

import { ECJsonMarkdownGenerator } from "@bentley/ecjsom2md";

mdGenerator = new ECJsonMarkdownGenerator(<array of search directories>);

mdGenerator.generate(<path to ECSchema JSON>, <output markdown file path>);

Note: Additional static methods are also available for more specific use

Updating

---

If installed globally

npm update -g @bentley/ecjson2md

If installed locally

npm update @bentley/ecjson2md

Use with Bemetalsmith

---

Bemetalsmith with plugin called addRemarks which can be used to splice human written notes into the files that are generated by ecjson2md. In most cases, Bemetalsmith will do this out-of-the-box without additional configuration.

Notes about use with Bemetalsmith

• The "-n" option in ecjson2md will generate short code for bemetalsmith to include an alert stating that the documentation is for an unreleased schema
• Human-written remarks must be contained in markdown files alongside the generated docs
• Each schema must have a separate remarks file if it has any remarks
• The name of the remarks file does not matter
• The front matter of the remarks file must point to the schema doc that it corresponds to (see below examples)
• The remarks are spliced in "as is" including any markdown tags

Schema doc structure after remarks are merged in

# <Name of schema>
.
.
.
## Classes
### <Name of class1>
.
.
.
**Base class: ** [link_to <schema name>/#<class name> text="<base class name>"]
.
.
.
<---- Human-written remark for class1 will go here
### <Name of class2>
.
.
.
<---- Human-written remark for class2 will go here
### <Name of class3>
.
.
.

How to create a remarks file

• At the top of the remarks file, include:

  ---
  remarksTarget: <name of target file>
  ---

• Add a remark after each ### header

Example

target.md		remarks.md
. . . ### Texture . . . ### TypeDefinitionElement . . . ### TypeDefinitionHasElement		--- remarksTarget: target.md --- ### Texture More information at docs.example ### TypeDefinitionElement *ready for release*

⇩ addRemarks ⇩

target.md		remarks.md
. . . ### Texture . . . More information at docs.example ### TypeDefinitionElement *ready for release* . . . ### TypeDefinitionHasElement		--- remarksTarget: target.md --- ### Texture More information at docs.example ### TypeDefinitionElement *ready for release*

Notes

---

• When using the CLI tool, providing a list of directories that are separated by comma + space such as: -r ./one, ./two, /three will only add the first directory to the locator. Use only a comma or quotes instead, e.g. -r ./one,./two,./three or -r './one, ./two, ./three'

Known issues

---

• None currently (as of 7/25/2018)