Skip to content

Convert AsciiDoc documentation to Markdown - #12389

Merged
romain-grecourt merged 2 commits into
helidon-io:mainfrom
romain-grecourt:main-docs-markdown
Sep 1, 2026
Merged

Convert AsciiDoc documentation to Markdown#12389
romain-grecourt merged 2 commits into
helidon-io:mainfrom
romain-grecourt:main-docs-markdown

Conversation

@romain-grecourt

@romain-grecourt romain-grecourt commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Description

Forward-port #12220 to main, converting AsciiDoc documentation to
Markdown.

The Markdown is flavored using HTML comment directives so the source still
renders as vanilla Markdown.

On main, the former Helidon SE content is published under the top-level
Modules and Guides sections. This forward-port also includes the reconciled
main-branch documentation updates.

The configuration documentation generator now outputs Markdown instead of
AsciiDoc, with simpler anchor handling for included pages. Generated
configuration docs are checked in under docs/config, and CI regenerates them
and fails if the checked-in output is out of date.

Aggregate Javadocs are generated from the dedicated javadocs/pom.xml module
instead of docs/pom.xml.

Documentation

This pull request is the main forward-port of the documentation conversion
in #12220. It publishes the former SE documentation as top-level Modules and
Guides, including generated Markdown configuration references.

Validation

Validation included:

  • focused configuration-reference generator tests, repeated stable Config
    generation, and the CI freshness check for checked-in docs/config output;
  • two byte-identical differential audit runs, with all 16 fixtures passing and
    zero actionable findings; and
  • checkstyle, copyright, ShellCheck, and whitespace checks.

@romain-grecourt romain-grecourt self-assigned this Aug 28, 2026
@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Aug 28, 2026
@romain-grecourt romain-grecourt added docs 27.x Issues for 27.x version branch labels Aug 28, 2026
@romain-grecourt romain-grecourt added this to the 27 milestone Aug 28, 2026
Comment thread etc/scripts/release.sh Outdated
Comment thread javadocs/pom.xml
Comment thread docs/guides/maven.md Outdated
Comment thread javadocs/pom.xml Outdated
@tomas-langer

tomas-langer commented Aug 30, 2026

Copy link
Copy Markdown
Member

Of the five review findings, these two are blockers and should be fixed as part of this PR before merge:

  • Restore the aggregate Javadocs main artifact in the validation-to-release cache handoff.
  • Correct the copyright notice in the newly added javadocs/pom.xml.

The remaining three findings can be addressed in a follow-up PR:

  • Update literal snapshot versions when preparing versioned documentation.
  • Update the obsolete generated-config URL in WebClientDiscovery Javadoc.
  • Point the v27 Maven guide to main-line application-POM guidance.

Convert AsciiDoc documentation to Markdown.

The Markdown is flavored using HTML comment directives so the source still renders as vanilla Markdown.

On `main`, the former SE content is published under the top-level Modules and Guides sections. This forward-port includes the reconciled main-branch documentation updates.

The configuration documentation generator now outputs Markdown instead of AsciiDoc, with simpler anchor handling for included pages. Generated configuration docs are checked in under `docs/config`, and CI regenerates them and fails if the checked-in output is out of date.

Aggregate Javadocs are generated by the dedicated `javadocs/pom.xml` module instead of `docs/pom.xml`.
@romain-grecourt
romain-grecourt merged commit 5b12b47 into helidon-io:main Sep 1, 2026
79 of 87 checks passed
@romain-grecourt
romain-grecourt deleted the main-docs-markdown branch September 1, 2026 01:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

27.x Issues for 27.x version branch docs OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants