english | русский

---

yfm-docs

Yfm-docs lets you build a full-fledged documentation project: with navigation, internal transitions, and full Yandex Flavored Markdown (YFM) support. For example, Yandex.Cloud documentation.

Installation

npm i @doc-tools/docs -g

Usage

yfm -i ./input-folder -o ./ouput-folder -v "{\"name\":\"Alice\"}"

List of possible parameters

• --input, -i

  Path to the project directory (required parameter).

• --output, -o

  Path to the output directory (required parameter).

• --allowHTML

  Allow the use of HTML in MD files.

• --varsPreset

  Name of the used preset.

• --vars, -v

  Values of YFM variables

• --strict, -s

  Start in strict mode.

  YFM warnings are treated as errors. Disabled by default.

• --quiet, -q

  Start in quiet mode.

  Do not output logs to stdout. Disabled by default.

• --config, -c

  Path to the YFM configuration file.

• --output-format

  Generation format: HTML or MD. By default, HTML.

• --apply-presets

  Shows whether to apply presets when converting md2md.

• --resolve-conditions

  Shows whether to apply conditions when converting md2md.

• --disable-liquid

  Indicates whether to disable the use of the template engine

• --ignore-stage

  Ignore tocs with stage.

• --publish

  Should upload output files to S3 storage. Disabled by default.

• --contributors

  Should attach files' contributors. Disabled by default.

• --version

  Current version.

• --help

  List of commands.

Learn more yfm-docs --help

Learn more about the project structure

Build result

The built project is a set of static HTML pages that can be viewed locally, hosted on a hosting service, on GitHub Pages, or in S3:

output-folder
|-- index.html (Documentation leading page)
|-- quickstart.html (Document files and images)
|-- pages
    |-- faq.html
    |-- how-to.html
|-- assets
    |-- image1.png
    |-- image2.png
|-- includes
    |-- faq_shared_block.html

Building a project in YFM

You can also build your project in YFM using the --output-format=md key.

In this case:

• Inserts in ToC files are applied.
• Conditions in the content and ToC files are calculated.
• Variables are applied if the apply-presets parameter is specified.
• All files specified in the ToC files, images used in them, and insert files will be copied.

Learn more about variables and conditions in YFM documentation.

input-folder
|-- index.yaml (Documentation leading page)
|-- quickstart.md (Document files and images)
|-- pages
    |-- faq.md
    |-- how-to.md
|-- assets
    |-- image1.png
    |-- image2.png
|-- includes
    |-- faq_shared_block.md

Source files

Preparation

You need to add .env file into repo root with data below:

GITHUB_OWNER= 
GITHUB_REPO= # docs
GITHUB_TOKEN= # personal access token
GITHUB_BASE_URL= # for ex: https://api.github.com
VCS_CONNECTOR_TYPE= # gitHub 

or you can update .yfm file into docs repo

connector:
    type:
    gitHub: 
        endpoint: 
        token: 
        owner: 
        repo: 

Installation

cd yfm-docs
npm ci && npm run build

Usage

npm run start -- -i ./input-folder -o ./ouput-folder -v "{\"name\":\"Alice\"}"

License

MIT