[phillip-kruger]

The docs move from MkDocs to AsciiDoc, laid out like the Quarkus guides. smallrye.io pulls them in and publishes them at https://smallrye.io/docs/smallrye-config// (smallrye/smallrye.github.io#136): main nightly, each release once it is tagged.

Depends on smallrye/smallrye.github.io#136. The new Documentation check calls the reusable workflow added there.

What changes

• Pages. documentation/src/main/docs/**/*.md become documentation/src/main/asciidoc/**/*.adoc with the same paths, so no page is renamed. config/mappings.md becomes config/mappings.adoc and is published at /docs/smallrye-config/<version>/config/mappings/.

  • The sidebar is in _nav.yml, and shared attributes are in _attributes.adoc.
  • Ids are Quarkus-style, e.g. #parent-profile.

• Versions. The dependency snippets use {project-version}, which smallrye.io sets for each release. This replaces attributes.yaml, which Maven filtered for MkDocs.

• Line breaks in property tables. The <br> between a property name and its description is now an AsciiDoc hard line break.

• Encryptor script. The jbang encryptor.java moves next to its page, and the command in the docs uses the new raw URL.

• PR check. Pull requests touching documentation/ run the Documentation workflow. It renders the docs with the smallrye.io site, fails on a broken include or a page that does not render, and attaches the rendered site as an artifact.

• Removed:

  • mkdocs.yaml, Pipfile/Pipfile.lock, the docissimo macros, attributes.yaml and its resource filtering;
  • the mike publishing: the docs job of Build, and the Publish Docs workflow with its call from Release.

  The release no longer publishes docs; smallrye.io picks up the tag.

• Docs and README links. documentation/README.adoc explains how to write and preview pages, and the README links point to the new location.

Older versions

Everything already on gh-pages (Main, Latest/4.0.0 and earlier) stays where it is, and the site's version picker links to it as "Older versions". After this is merged, the mike Latest/Main aliases and the root page on gh-pages will redirect to /docs/smallrye-config/latest/.

Checked

• The 28 pages render with the smallrye.io site, with no errors or Asciidoctor warnings.
• All 1,418 internal links and every in-page anchor resolve.
• mvn -pl documentation -am install still builds.

[phillip-kruger]

Screenshots of the documentation before and after this change (updated).

Before: the MkDocs site, as it is on smallrye.io today. After: this branch's AsciiDoc, rendered by smallrye.io with smallrye/smallrye.github.io#136 (a local build: /docs/smallrye-config/main/). 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; further down, a start page lists the documentation, from its navigation.

Before	After
Start page · old page
Mappings · old page
Mappings, with the Contents sidebar open

Dark theme: the same screenshots with the dark theme

The old Antora sites and the GraphQL, Vert.x bindings and Mutiny Zero MkDocs sites have no dark theme, so their "before" stays light; the other old MkDocs sites were switched to their own dark palette.

Before (dark theme)	After (dark theme)
Start page · old page
Mappings · old page
Mappings, with the Contents sidebar open