Repository navigation
Publish all project documentation on smallrye.io, from the projects' repositories - #136
Open
phillip-kruger wants to merge 14 commits into
Open
phillip-kruger wants to merge 14 commits into
phillip-kruger wants to merge 14 commits into
Conversation
Projects keep their documentation in their own repository, as AsciiDoc laid out like the Quarkus guides, and this site pulls it in and publishes it at /docs/<project>/<version>/. - data/docs.yml lists every project with documentation; the /docs/ hub is generated from it and replaces the Antora start page. - tools/docs/sync.py copies a project's docs from a branch, tag or local checkout into content/docs/<project>/<version>/, with only the example files the pages include, and records versions and navigation in data/docversions.yml. A release whose docs are still MkDocs is converted on the fly by tools/docs/mkdocs2adoc.py, also the one-off converter. - The "Sync project documentation" workflow runs it nightly (main and the newest release tag) and commits to develop; "Check project documentation" is a reusable workflow projects call from pull requests to render their docs with this site. - Docs pages get a layout with the project's sidebar, a version picker (with the pre-move versions as "Older versions"), an on-this-page list, tabs, and a fix-up for #_old_style ids. - SmallRye GraphQL is the first project: 3.0.0.Beta8 as latest, and main. - Antora output is now merged into the Roq docs directory instead of replacing it, and its playbook includes the Fault Tolerance 7.x tags, so 7.0.0's documentation is published. - Blog posts no longer link to SmallRye Config pages that no longer exist.
… and bad ids The docs check renders contributors' pull requests, so their docs are untrusted: - symbolic links in a docs directory are skipped, and an included example must resolve inside the examples directory; - version ids, refs and nav page names are checked before they become paths, and nav links must be http(s) (the sidebar template checks again); - Asciidoctor's SAFE-mode jail is now the site root instead of each page's directory, so a page in a subdirectory can include its version's _attributes.adoc and examples while nothing outside the site can be included. Also: pages in subdirectories are highlighted in the sidebar and get the right edit link, and synced pages get an absolute imagesdir.
examples-dir comes from the project's _attributes.adoc, so it is now checked to stay inside
the checkout too, not only the includes below it; an included example is written to the path
it resolves to, never to its raw include path; and a symbolic link resolving outside the docs
directory is skipped.
The synced examples-dir is {version-root}_examples, with version-root empty by default, so a
page in a subdirectory (setting :version-root: ../) finds its version's examples.
… to the site The four projects built with Antora are now published like GraphQL, from their repositories, and Antora leaves the build (with its playbook and the Kroki services it needed). - tools/docs/antora2adoc.py converts an Antora component to the Quarkus-style layout: pages keep their paths (so their addresses), partials and examples move under _partials/ and _examples/, nav.adoc becomes _nav.yml, antora.yml attributes become _attributes.adoc, and pages in subdirectories set :version-root: so shared paths resolve from any depth. The sync uses it for releases whose docs are still Antora. - Fault Tolerance: latest (7.0.0), main, and the 6 and 5 release lines; Health and JWT: latest and main; Metrics, archived: its 3.0 and 2.4 lines, with an "archived" notice. - Version ids carry no dots (Roq turns them into hyphens in addresses); the version picker and the hub show the release number instead. - Diagram blocks are rendered to SVG once, during the sync, by a Kroki server; the docs workflows run one. - Every address Antora published (/docs/<project>/<release>/<page>.html, 1,524 of them) gets a redirect page at build time (tools/docs/redirects.py) to the same page in the version that replaces it, keeping the #fragment; docs pages map Antora's #_generated_ids to the new ids. - Blog posts link to the new addresses (tools/docs/rewrite-links.py, which checks each page and anchor against the generated site), including sections renamed in later releases.
…Messaging, Stork, ...)
Every SmallRye project with documentation is now on the site: Config, Mutiny, Mutiny Zero,
Mutiny Vert.x bindings, Reactive Messaging, Stork and Jandex join GraphQL and the former
Antora projects. Until their repositories carry AsciiDoc, each release is converted on the fly.
The MkDocs converter now covers what these projects use:
- docissimo macros: insert() becomes an include with tags (the <tag> comment markers of the
examples become tag::/end:: markers, in place or on the synced copies), javadoc() a
javadoc.io link, image() a titled image; attributes.yaml values become attributes, Maven
${...} placeholders resolved from the poms;
- pages in subdirectories (version-root), links relative to the page, images relative to the
version, Markdown files other pages insert (partials), code fences with pymdownx options
(title= becomes the block title), attributes inside listings, "!!!note" without a space
and with an unindented body, no TeX math in "$Key ... $Value";
- build_plantuml diagrams: the .puml sources (includes inlined, light theme) are rendered by
the sync like other diagram blocks.
The sync also:
- takes generated files from the released jars on Maven Central (Reactive Messaging's
connector attribute tables, META-INF/connector/*.md), converted to AsciiDoc;
- drops navigation entries without a page, and points xrefs to index.adoc at the directory.
Checked: no rendering errors or Asciidoctor warnings except Reactive Messaging's own (its
RabbitMQ pages include examples that do not exist in its repository, one example lacks an
end marker, and 5.0.0-RC1 links to a page it does not have: 2 broken links out of 52,017).
phillip-kruger
changed the title
For the cutover of each project: in a checkout of its gh-pages branch, the moving mike aliases (latest, Latest, Main, ...; symlinks are replaced by directories) and the root page become redirect pages to the same page under /docs/<project>/latest/, or to its start page when the page no longer exists. Released versions stay as they are: the site links them as older versions.
This was referenced Oct 15, 2026
Open
Attributes defined from {project-version} (such as Config's version) resolved before the sync's
own value was set; it now comes first. main gets the newest release, the version readers put in
their builds, and javadoc links use the same. Table cells keep their <br> line breaks.
From the project PRs (Config, Mutiny, Stork, Health, JWT, Mutiny Zero, Vert.x bindings): - MkDocs: --8<-- snippets outside code blocks (Stork's attribute tables); #only-light/ #only-dark image pairs keep the light one; Material icon shortcodes and the tags placeholder are dropped and page tags become :topics:; links to a heading by its text (#Some Heading) point to its id; ./page nav entries keep their page; the aggregated apidocs nav entry links to javadoc.io; snippet prefixes can be regular expressions. - Antora: an anchor right above the title is dropped, <<id>> to another page becomes an xref, and the nav's "Index" is "Overview". - Generated files: Stork's attribute tables come from its jars (META-INF/stork-docs/, Markdown in .txt); Mutiny Zero's examples resolve from the repository root. - The reusable docs check runs read-only: it renders pull-request content.
…butes in page titles, highlight Groovy
Member
Author
|
Screenshots of each project's documentation before (its MkDocs or Antora site today) and after (the project's AsciiDoc from its PR, rendered by this branch locally), updated for the header and sidebar changes. On smallrye.io the sidebar starts closed (the ☰ button opens it, and it stays open on the next pages for that reader); its groups are folded except the one holding the current page. The project and version picker sit in the header next to the logo, so a start page has no separate title. Each project PR has more pages, including one with the sidebar open.
|
||||||||||||||||||||||||||||||||||||||||||||||||||
…, folding sidebar sections
Member
|
Hey @phillip-kruger, this looks amazing! One question: are we supposed to merge your PRs in the individual projects before this one is merged, or after? Or it doesn't matter? |
Member
|
Oh one more thing: the way we preview individual project docs locally is not good. I mean, it's probably the best we can do at the moment, and I usually don't mind because IntelliJ's built-in Asciidoc renderer is good enough for most cases, but when it's not... Well, I guess I'll get used to it. At least it's documented :-) |
Member
Author
|
Thanks @Ladicek! Best is this one first, then the project PRs in any order.
|
Member
|
OK, thanks! I'll review the PRs but wait with merging until this is done. |
Member
Author
|
@Ladicek I'll add something that make local preview easier. |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every SmallRye project's documentation is now published on this site at
/docs/<project>/<version>/, from the project's own repository, as AsciiDoc laid out like the Quarkus guides. Antora leaves the build, and the per-project MkDocs/mike sites are replaced.Each project gets a PR moving its sources to AsciiDoc (smallrye/smallrye-graphql#2732 first). The site does not wait for those PRs: a release whose docs are still MkDocs or Antora is converted on the fly, so all current releases are published as soon as this is merged.
How it works
data/docs.ymllists every project with docs: repository, docs path, the versions followed, and the addresses published before. It also drives the/docs/hub.tools/docs/sync.pycopies a project's docs from a branch, tag or local checkout intocontent/docs/<project>/<version>/, and records versions and navigation indata/docversions.yml. It also:tools/docs/mkdocs2adoc.pyandtools/docs/antora2adoc.pydo the one-off conversion of a project, and the on-the-fly one. The MkDocs converter covers the docissimo macros (insert,javadoc,image, attributes), admonitions, tabs, PlantUML and nested pages.develop./docs/<project>/<release>/<page>.html) to the same page in the version replacing them.#_snake_caseanchors are mapped to the new Quarkus-style ids.tools/docs/rewrite-links.pychecked each page and anchor against the generated site, including sections renamed in later releases.Security
The PR check renders untrusted pull-request content, so:
Checked locally
After merge
CI_APP_ID/CI_APP_PRIVATE_KEY) is reused by the sync workflow.main.gh-pages, the moving mike aliases (latest,Latest,Main) and root pages become redirects to/docs/<project>/latest/. Released versions stay as the archive. Jandex's Antora site gets the same treatment.