omnidocs/markdown API reference

Omnidocs\Markdown

Changelog class

final class Changelog Changelog.php:17

A changelog in Markdown read as releases: each second-level heading that starts with a version - "## 1.5.3 - 2026-10-25", "## [1.2.0] - 2026-10-11", "## v2.0.0 (2026-01-05)" - is a release, its date when the heading gives one, its anchor in the rendered page. "## Unreleased" is not a release.

$changelog = Changelog::read('CHANGELOG.md'); $changelog->versions(); // ['1.5.3', '1.5.2', ...], newest first, as written $changelog->release('1.4.0'); // ['version' => '1.4.0', 'date' => '2026-10-17', 'id' => '140---2026-10-17']

public readonly Rendered $rendered

Changelog::__construct()

public function __construct(public readonly Rendered $rendered)

Changelog::read()

public static function read(string $file, ?MarkdownRenderer $renderer = null, ?callable $links = null): self

Changelog::releases()

public function releases(): array

Returns

newest first, as written

Changelog::versions()

public function versions(): array

Changelog::knownVersions()

public function knownVersions(): array

Every version, and its minor too ("1.5.3" also gives "1.5"): what a heading of the manual may say a feature came with.

Changelog::release()

public function release(string $version): ?array

Changelog::firstOf()

public function firstOf(string $minor): ?array

The first release of a minor version ("1.4" → the 1.4.0 entry, or the oldest 1.4.x).

MarkdownRenderer class

final class MarkdownRenderer MarkdownRenderer.php:60

Markdown as a manual's page: CommonMark with GitHub's extensions (tables, task lists, autolinks, strikethrough), a front matter, an id on every heading, and symfony.com/doc's conventions written the way GitHub reads them too:

• callouts: a quote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION], [!SEEALSO]; [!VERSIONADDED] 1.4 and [!DEPRECATED] 2.0 carry their version;
• code in a frame that names its language (frames), with a caption: ``js caption="app.js"``; blocks that follow each other with a tab="..." each are shown in tabs;
• a heading that ends with a version the manual knows ("Keys (1.4)", versions) gets a version badge in place of it - its anchor unchanged;
• the first first-level heading is the page's title, printed by the page rather than in the prose.

Raw HTML is escaped: a manual comes from a repository and is not trusted to write a site's markup - but for the tags inline_html allows, written bare (<kbd>, no attribute).

$links rewrites each link and picture: it receives the address as written and whether it is a picture, and answers the one to print, or null to keep it.

MarkdownRenderer::__construct()

public function __construct(array $labels = [], readonly bool $frames = true, array $inlineHtml = [], array $versions = [])

$labels

the callouts' labels (Conventions::LABELS' keys)

$frames

every code block in its frame; false: only those with a caption

$inlineHtml

the tags a page may write bare: ['kbd']

$versions

the versions a heading may end with: ['1.4', '1.5.0']

MarkdownRenderer::conventions()

public function conventions(): Conventions

MarkdownRenderer::render()

public function render(string $markdown, ?callable $links = null): Rendered

MarkdownSource class

final class MarkdownSource implements SourceInterface MarkdownSource.php:31

A folder of Markdown files as a manual, as a repository keeps it:

• the folders are sections, the files pages, ordered by their front matter's order (or weight, sidebar_position), else by a number before their name ("10-getting-started.md", the number out of the address), then by name - or as order lists them;
• a page's title is its front matter's title, else its first first-level heading, else its name;
• the home is index.md or README.md at the folder's root (or home, a file anywhere in the repository: its README);
• pages adds files from elsewhere in the repository after the folder's own (a CHANGELOG): ['changelog' => 'CHANGELOG.md'].

Links between pages go to their pages (with or without ".md"), to any other file of the repository to that file (the linker's file()), pictures to the linker's image(), paths read from the folder of the file they are written in.

new MarkdownSource('/path/to/checkout', 'docs', home: 'README.md');

MarkdownSource::__construct()

public function __construct(string $root, string $docs = 'docs', readonly string|false|null $home = null, readonly array $pages = [], readonly array $order = [], readonly array $exclude = [], readonly ?MarkdownRenderer $renderer = null, readonly string $repository = '')

$root

the folder on disk the paths are read from: a checkout, or a docs/ folder fetched alone

$docs

the folder of the pages under $root ("docs"; "" for $root itself)

$home

the home page's file under $root; null: index.md or README.md of $docs; false: none

$pages

pages from other files under $root, after the folder's own: [path => file]

$order

the first pages and sections in this order, by path; the rest after

$exclude

files and folders of $docs left out (fnmatch patterns, relative to $docs)

$repository

what $root is in the repository ("" its root; "docs" for a docs/ folder fetched alone)

MarkdownSource::home()

public function home(): ?Node

MarkdownSource::tree()

public function tree(): array

MarkdownSource::page()

public function page(string $path, ?LinkerInterface $links = null): ?Page

MarkdownSource::symbols()

public function symbols(): array

MarkdownSourceFactory class

final class MarkdownSourceFactory extends SourceFactory MarkdownSourceFactory.php:24

The "markdown" source:

root the folder the paths are read from (a checkout) required docs the folder of the pages under root "docs" home the home's file under root; false for none index.md or README.md of docs pages other files as pages, after the folder's: [path => file] order the first pages and sections, by path, in their order exclude files of docs left out (fnmatch patterns) repository what root is in the repository ("docs" for a docs/ folder fetched alone) labels the callouts' words (note, tip, versionadded...) frames every code block in its frame (true) inline_html the tags a page may write bare: [kbd] versions the versions a heading may end with, for its badge

Options

MarkdownSourceFactory::getName()

public function getName(): string

Omnidocs\Markdown\Node

CodeTabs class

final class CodeTabs extends AbstractBlock CodeTabs.php:8

Fenced code blocks that follow each other, each with its tab="..." - shown one at a time.

public readonly string $id

CodeTabs::__construct()

public function __construct(public readonly string $id)

RawHtml class

final class RawHtml extends AbstractInline RawHtml.php:12

HTML the renderer itself writes into a page: a tag of the allowed list (<kbd>), a version badge. Not a string container: a heading's text, a search index's, does not read it.

public readonly string $html

RawHtml::__construct()

public function __construct(public readonly string $html)