Skip to content

feat(build): include code from external sources - #2209

Open
vgvoleg wants to merge 3 commits into
diplodoc-platform:masterfrom
vgvoleg:feat/external-code-sources
Open

vgvoleg wants to merge 3 commits into
diplodoc-platform:masterfrom
vgvoleg:feat/external-code-sources

Conversation

@vgvoleg

@vgvoleg vgvoleg commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Closes #2207

Adds {% include-code %}: a document references a file in an external source, and the build embeds
its content instead of a hand-written copy.

code-sources:
  python-sdk:
    type: git
    repo: ydb-platform/ydb-python-sdk
    ref: main
    path: examples
{% include-code [Connecting to a database](python-sdk:static-credentials/example.py#auth-static) %}

Three source types: git (a repository on a hosting service), http (plain files), local (a
directory on disk). Fragments are addressed by named regions (#region name or [START name]),
line ranges are supported but warned about.

Notes:

  • Nothing is cloned and no git binary is used: the ref is resolved over git smart HTTP, then only
    the referenced files are downloaded. One file out of a large monorepo costs kilobytes.
  • The directive is lowered to an ordinary fenced block before the rest of markdown processing, so
    HTML, PDF, single-page, md2md, search and llms.txt need no changes.
  • Links are pinned to the resolved commit, with line numbers derived from the region.
  • A missing region fails the build — that is the point: it turns silent doc rot into a build error.

Two additions outside the feature directory: Run.addScope, so downloaded files are read through the
existing path sandbox rather than around it, and an export of findFencedCodeBlockRanges, so a
directive shown as a code example is left alone by the same rule {% include %} uses.

Not covered: private repositories, a lock file, incremental/watch tracking of external files.
User documentation will follow as a separate PR to diplodoc-platform/docs.

Add {% include-code %} to embed files from git hosting, HTTP storage or
local directories at build time.
@vgvoleg
vgvoleg requested review from a team and diplodoc-bot as code owners August 19, 2026 12:32
@vgvoleg
vgvoleg requested review from martyanovandrey and separatrixxx and removed request for a team August 19, 2026 12:32
@martyanovandrey

Copy link
Copy Markdown
Contributor

Thanks! We're discussing the approach internally with the author, will follow up here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Встраивание файлов из внешних источников ({% include-code %})

2 participants