Show source code on a wiki page

Situation

The repository is mounted and should now appear on a wiki page — either the whole tree for browsing, or a single file or range of lines beside an explanation.

Solution overview

There are two markups. Mistaking one for the other is the commonest error when embedding.

Markup	What it shows	Who renders it	Where it works
`{{wk:adogit>…}}`	a tree of the whole repository's folders and files	the `wkdoadogit` plugin	only on a page below the project root, such as `en:projects:dwplugins:repos`
`{{source>ado:…}}`	the content of a single file	the `wksourceview` plugin through the `ado` scheme	on a page below the project root, or on a page inside the mount namespace

Both run through the same permissions: access is decided by the mount namespace, never by the page the markup sits on.

Implementation

The repository tree

{{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit}}

The grammar is {{wk:adogit>connection:project:repo[:ref[:path]]}}. An omitted ref means the repository's default branch, an omitted path means the root. The optional region=<name> suffix offers the browser to a side region of the shell:

{{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain region=toc}}

A single file

{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain/MountAclGate.php}}

The grammar is {{source>ado:connection:project:repo:ref:path}}. All five fields are mandatory for this markup, so always name the branch. An empty field means refusal, not the default branch.

A range of lines

{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain/MountAclGate.php#L141-L146}}

The permitted forms are #L25, #L10-L40 and the open-ended #L10-. Counting starts at 1 and the range is clamped to the length of the file. The range is display-only: the whole file is always transferred from Azure DevOps.

Display options

Write options after a space. They apply to wksourceview, not to the ado scheme.

{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/README.md#L1-L20 mode=block numbers=1 lang=markdown}}

Option	Values	Default
`mode`	`inline`, `block`, `preview` or `drawer`	the value of the `default_mode` setting of `wksourceview`
`numbers`	`0` or `1`	the value of the `default_numbers` setting
`lang`	language name for syntax highlighting	detected from the file extension

Remarks

The first field is the connection key, not its number. The connection is looked up by key inside the DWDO project the page belongs to; a numeric form does not work.
Every embed is a network call. A page with a dozen embeds pays for a dozen calls, bounded by the timeouts and the byte ceiling in wkdoado.
An embed pinned to a branch drifts silently. Text explaining line 40 keeps rendering after the code has moved to line 90. For explanations, pin a commit (40 hex characters) rather than a branch.
A page with an embed is not cached. Both markups switch off the page cache, so permission-guarded content never reaches the wrong reader.
Oversized and binary files are not rendered. A state card appears instead of the content; the limits are set by max_bytes and max_lines of wksourceview.
A refusal does not name its cause. An unmounted repository, an unknown connection and a missing permission answer deliberately alike.