Skip to content

[#182] Fix Asciidoctor warnings in the OpenIG guides - #184

Open
vharseko wants to merge 1 commit into
OpenIdentityPlatform:masterfrom
vharseko:docs-asciidoctor-warnings
Open

vharseko wants to merge 1 commit into
OpenIdentityPlatform:masterfrom
vharseko:docs-asciidoctor-warnings

Conversation

@vharseko

Copy link
Copy Markdown
Member

Fixes #182

Changes

  • partials/sec-release-levels.adoc: removed the [appendix], [#appendix-interface-stability], == Release Levels and Interface Stability heading and the intro paragraph. They repeated the heading of reference/appendix-interface-stability.adoc, which includes this partial. On the site the converter adds :leveloffset: -1 to the page, so the repeated == became a level-0 section (level 0 sections can only be used when doctype is book), and its id was assigned twice (id assigned to section already in use: appendix-interface-stability). The rendered page also had an empty <h2 id="appendix-interface-stability">; the PDF book had the appendix heading nested in itself. The heading and intro stay on the including page.
  • reference/handlers-conf.adoc: the nested [open] + ==== block of the Router openApiValidation properties (added in OpenAPI/Swagger routes loader and request/response validator #150/Add OpenApiMockResponseHandler — spec-driven mock API with realistic test data #155) was never closed — the enclosing -- came right after it (unterminated open block). Added the closing ==== after mockMode.

The releaseversion: 5.2.4 in the component descriptor, also mentioned in the issue, lives in doc.openidentityplatform.org and is not changed here.

Verification

  • asciidoctor.js over reference/index.adoc and gateway-guide/index.adoc: before — unterminated example block at handlers-conf.adoc:780/781; after — no messages.
  • Antora 3.1.15 build of doc.openidentityplatform.org (ROOT + openig components) with the same changes applied to the converted pages: the three messages from the issue are gone and no new ones appear. The appendix page renders without the empty heading; the openApiValidation options render as two open blocks with mockMode inside.
  • Not in scope: the 10 skipping reference to missing attribute warnings (${true}, ${userid}, …) in expressions/filters/handlers/chap-auditing — the text renders as written.

- partials/sec-release-levels.adoc: drop the appendix heading, id and intro
  that duplicated the including appendix page; with the leveloffset added for
  Antora the heading became a level-0 section and its id was assigned twice.
- reference/handlers-conf.adoc: close the nested [open] ==== block of the
  Router "openApiValidation" properties before the enclosing "--" block.

Fixes OpenIdentityPlatform#182
@vharseko vharseko added bug documentation Improvements or additions to documentation labels Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: fix Asciidoctor build warnings

1 participant