Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/itwin/ecjson2md
A CLI tool that is used to generate Markdown files based upon ECSchemas.
https://github.com/itwin/ecjson2md
bentley bis chai ecschemas imodeljs markdown typescript
Last synced: 3 months ago
JSON representation
A CLI tool that is used to generate Markdown files based upon ECSchemas.
- Host: GitHub
- URL: https://github.com/itwin/ecjson2md
- Owner: iTwin
- License: mit
- Created: 2021-10-26T18:43:18.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-23T06:40:12.000Z (3 months ago)
- Last Synced: 2024-11-07T15:58:39.779Z (3 months ago)
- Topics: bentley, bis, chai, ecschemas, imodeljs, markdown, typescript
- Language: TypeScript
- Homepage: https://github.com/iTwin/bis-schemas
- Size: 1.11 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 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](https://github.com/iTwin/ecjson2md/tree/master/CHANGELOG.md)
## Installation
---------------------------------------------------------------
### Install globally (recommended)
```sh
npm install -g @bentley/ecjson2md
```
### Install locally
```sh
npm install @bentley/ecjson2md
```
## Usage
---------------------------------------------------------------
### Generate a markdown file from ECSchema JSON via command line
```sh
ecjson2md -i -r -o
```
_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
```Typescript
import { ECJsonMarkdownGenerator } from "@bentley/ecjsom2md";
mdGenerator = new ECJsonMarkdownGenerator();
mdGenerator.generate(, );
```
_Note: Additional static methods are also available for more specific use_
## Updating
---------------------------------------------------------------
### If installed globally
```sh
npm update -g @bentley/ecjson2md
```
### If installed locally
```sh
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
```markdown
#
.
.
.
## Classes
###
.
.
.
**Base class: ** [link_to /# text=""]
.
.
.
<---- Human-written remark for class1 will go here
###
.
.
.
<---- Human-written remark for class2 will go here
###
.
.
.
```
### How to create a remarks file
- At the top of the remarks file, include:
```markdown
---
remarksTarget:
---
```
- 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)