[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-graphql// (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. docs/*.md become docs/src/main/asciidoc/*.adoc with the same names. The exceptions are server_configuration and client_configuration, which become server-configuration and client-configuration.
  • The sidebar is in _nav.yml and shared attributes are in _attributes.adoc.
  • Ids are Quarkus-style, e.g. #name-mapping-aliases.
• Code examples. They move from docs/snippets to docs/src/main/java, the module's standard source directory, so the build-helper plugin goes. They still compile with the build, and pages include them with include::{examples-dir}/...[].
• PR check. Pull requests touching docs/ 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.yml, the mike Publish the website workflow, and .github/render-documentation.sh. The release no longer publishes docs; smallrye.io picks up the tag.
• Docs and README links. docs/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 (3.0.0.Beta8 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 alias and the root page on gh-pages will redirect to /docs/smallrye-graphql/latest/.

Checked

• The converted pages render without errors or Asciidoctor warnings.
• All internal links resolve.
• The examples compile (mvn -pl docs -am install).

[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-graphql/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
Overview · old page
Further down the start page: its contents, listed from the navigation
Type-safe client · old page
Type-safe client, 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)
Overview · old page
Further down the start page: its contents, listed from the navigation
Type-safe client · old page
Type-safe client, with the Contents sidebar open