gem-hunter

english | русский

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

ydocs.tech

Node 22+

npm i @diplodoc/cli -g

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

Initialize a new Diplodoc documentation project.

yfm init [options]

Running without flags in a terminal starts an interactive wizard. Pass --skip-interactive to use flags and defaults only.

minimal

<output>/
├── .yfm
├── toc.yaml
└── index.md

full — adds presets.yaml, pc.yaml and extended .yfm with pdf, search, vcs, authors config.

For multilingual projects (--langs en,ru) content is placed in per-language subdirectories:

<output>/
├── .yfm
├── presets.yaml
├── en/
│   ├── toc.yaml
│   └── index.md
└── ru/
    ├── toc.yaml
    └── index.md

Process a single Markdown file and print the result to stdout (or write it to a file). Unlike yfm build, it does not traverse the whole project and does not produce a full page — for html it emits only the content fragment (no toc, header or page chrome).

# self-contained markdown to stdout
yfm content -i ./page.md -f md

# html content fragment into a file
yfm content -i ./page.md -f html -o ./page.html

The result printed to stdout is wrapped in delimiter markers so it can be extracted from the surrounding diagnostic output:

<<<<<< YFM CONTENT START >>>>>>
...content...
<<<<<< YFM CONTENT END >>>>>>

Warnings and errors go to stderr; on any build error the process exits with a non-zero code. When -o is used, the raw content is written to the file (without the markers).

Pass --raw to print only the content to stdout — without the delimiter markers and without the framework banners (version line, build timer, completion banner). This is handy when piping the result straight to another tool or file:

yfm content -i ./page.md -f md --raw > page.md

--raw has no effect together with -o (file output is always raw).

Presets (presets.yaml), includes and variables are resolved relative to a project root:

• by default the root is the current working directory;
• pass -c, --config <path> to point at a .yfm — its directory becomes the root.

HTML builds report a missing local link anchor as YFM025 / missing-local-anchor. It is a warning by default, including when an existing .yfmlint config sets YFM002 to error. Missing or unreachable target documents still produce YFM003 errors.

Literal browser fragment directives such as #:~:text=Selected%20text and #section:~:text=Selected%20text are excluded from local-anchor validation. The target document is still checked. Percent-encoded literal IDs remain subject to ordinary anchor validation.

Configure the new rule independently in .yfmlint:

YFM025: warn

Use YFM025: error to fail builds on missing local anchors or YFM025: false to disable the check. --strict continues to fail builds on warnings.

YFM024 / empty-custom-heading-anchor belongs to yfmlint and reports an empty shorthand heading ID, for example {# section-id}. It is independent of the CLI-only YFM025 check: severity settings and inline suppression apply separately. If a configuration adopted the temporary CLI-master YFM024 local-anchor check, use YFM025 or the unchanged missing-local-anchor alias for that check instead.

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:

cd cli
npm ci && npm run build

MIT