omnidocs / markdown
Omnidocs Markdown: a folder of Markdown files as an omnidocs manual - its contents from the folders and the files (their front matter, a number before their name), each page rendered with league/commonmark as symfony.com/doc writes its pages: callouts (note, tip, caution, versionadded...), code with
Requires
- php: >=8.2
- league/commonmark: ^2.6
- omnisense/omnidocs: ^1.0
- symfony/yaml: ^6.4|^7.0|^8.0
Requires (Dev)
- omnisense/contracts: ^1.0
- phpunit/phpunit: ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A folder of Markdown files as an omnidocs manual, each page rendered with league/commonmark as symfony.com/doc writes its pages - in a syntax GitHub reads too:
> [!NOTE] > Requires PHP 8.2. > [!VERSIONADDED] 1.4 > An arrow shows a tall section's end. ```js caption="app.js" StickyStops.attach(window, { keys: true });
flow: { keys: true }
$flow = ['keys' => true];
Sideways (1.5)
- the folders are sections, the files pages, ordered by their front matter (`order`, `weight`,
`sidebar_position`) or a number before their name (`10-install.md`), or by the `order` option;
- a page's title is its front matter's `title`, else its first first-level heading (taken out of the
prose: the page prints it), else its name;
- the home is index.md or README.md (or the `home` option: the repository's README); `pages` adds
other files (a CHANGELOG);
- links between pages go to their pages, links to other files of the repository and pictures to the
linker's addresses (the commit read, on GitHub);
- callouts, code frames and tabs follow omnidocs' conventions; a heading ending with a version the
manual knows (`versions`, e.g. `Changelog::read('CHANGELOG.md')->knownVersions()`) shows a badge;
- raw HTML is escaped - but for the tags `inline_html` allows, written bare (`<kbd>`).
## Installation and a first use
```sh
composer require omnidocs/markdown
It needs PHP 8.2 and no outside tool (league/commonmark and symfony/yaml come with it); no network, no account. A first manual, of this package's own README and CHANGELOG, installed with it:
require __DIR__.'/vendor/autoload.php'; use Omnidocs\Model\Version; use Omnidocs\Markdown\MarkdownSourceFactory; $source = (new MarkdownSourceFactory())->create(['root' => __DIR__.'/vendor/omnidocs/markdown', 'home' => 'README.md', 'pages' => ['changelog' => 'CHANGELOG.md']]); $version = new Version('1.x', $source); foreach ($version->pages() as $node) { echo $node->title, "\n"; }
Its tests (composer install then vendor/bin/phpunit in a checkout, or every package at once in
omnidocs' Docker harness)
read the folders committed under Tests/Fixtures; nothing else is needed.
A manual's options in full:
use Omnidocs\Markdown\{Changelog, MarkdownSourceFactory}; $source = (new MarkdownSourceFactory())->create([ 'root' => '/path/to/flowjs', 'home' => 'README.md', 'pages' => ['changelog' => 'CHANGELOG.md'], 'order' => ['navigation', 'sticky', 'sortable', 'ajaxer', 'cookie'], 'inline_html' => ['kbd'], 'versions' => Changelog::read('/path/to/flowjs/CHANGELOG.md')->knownVersions(), ]);
MarkdownRenderer alone renders any Markdown text (a guide, a piece of news) to Rendered: HTML,
title, headings, front matter, plain text. Changelog reads a changelog's releases (version, date,
anchor). Options: docs/index.md.
Verified, and not
- Verified (omnidocs' harness, PHP 8.4): omnidocs' conformance suite on flowjs' docs/, README and
CHANGELOG (copied at the commit in Tests/Fixtures/flowjs/COMMIT) and on a folder written for the
test (sections, numbers, front matter, every kind of link); the renderer's callouts, frames, tabs,
badges, allowed tags;
BareTest. - Verified in use: the Omnisense site renders its guides, news and 153 package manuals with it - its static export the same as with its former renderer, byte for byte but the build's own version; the flowjs site its manual and changelog.
- Not verified: Markdown written for other generators' extensions (MkDocs admonitions
!!! note, Docusaurus':::tip) - shown as written.
Licence: MIT.