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)