ammachado commented on issue #1746:
URL: https://github.com/apache/camel-website/issues/1746#issuecomment-5656992340
I reproduced this and confirmed the root cause, but `parseNoneClosedTags:
true` is not enough on its own.
### Root cause: confirmed
In `node-html-parser` 7.0.1, an unmatched `</code>` that arrives while
`<strong>` is open is dropped (`dist/nodes/html.js`, the "aggressive strategy"
`break`). Every later `</p>`, `</div>` and `</article>` is then dropped too. At
end of input, `parse()` unwraps each element still open, including
`article.doc`, `main` and `article`, so all four selectors miss and the page is
skipped.
### Why `parseNoneClosedTags: true` is not enough
The option skips the unwrap, so `article.doc` survives. But the unclosed
`<code>` stays open and swallows the rest of the article. Turndown's
inline-code rule then collapses it onto one line. I rendered the real sources
with Asciidoctor.js and ran the converter:
| Page | today | `parseNoneClosedTags` | browser-style repair |
|---|---|---|---|
| camel-jbang-mcp | skipped | 475 lines, 51 headings | 465 lines, 51
headings |
| camel-jbang-tui | skipped | 144 lines, 8 headings, one 59,380-char line |
992 lines, 75 headings |
| security-model | skipped | 125 lines, 9 headings, one 76,012-char line |
597 lines, 37 headings |
For two of the three pages, everything after the first glitch becomes a
single inline code span. `llms.txt` would then advertise a `.md` that is
quietly wrong, which is arguably worse than the 404.
### Fix: #1750
#1750 repairs malformed pages the way a browser does before extracting the
article. `jsdom` (built on the WHATWG `parse5` parser) is already a direct
dependency of the root package, though none of the gulp tasks use it:
```js
const repaired = !valid(htmlContent);
const root = parse(repaired ? new JSDOM(htmlContent).serialize() :
htmlContent);
```
- `valid()` is `base_parse(html).length === 1`. That is exactly the
condition under which `parse()` runs its destructive unwrap, so well-formed
pages skip jsdom and convert byte-identically to today.
- Repaired pages are logged (`Repaired malformed HTML in <file>`), and pages
with no main content are logged instead of skipped silently. Each Jenkins build
then names the sources that still need fixing.
- I verified this on a full production Antora build (5,432 pages). The
current converter skips 35 pages, which are exactly the 35 missing in
production. With the fix, `gulp generate-markdown` converts all 5,432 pages and
logs one repair warning for each of the 35. Nothing is skipped, and no Markdown
line runs away. The gate adds about 10 s to the task.
### Upstream sources
The set of 35 pages checks out against `camel-website-pub` `asf-site`, with
two corrections:
- `components/next/others/leveldb` isn't published (only 4.18.x and 4.22.x),
so the list in the description has 36 entries.
- The third non-doc file is `schema/spring/HEADER.html`, not `index.html`
(the generator's glob already excludes `index.html`).
Three AsciiDoc inline patterns cause every hit:
- **A (about 95% of hits):** a `*` inside backticks pairs with another `*`
(a wildcard or real `*bold*`) and emits `<code>…<strong></code>…</strong>`. It
only triggers when the `*` follows a non-word character, so `` `core/camel-*`
`` and `` `mail.smtp.*` `` break while `` `Camel*` `` alone may not.
- **B:** a `#` inside backticks pairs as `#highlight#` and emits
`<code><mark></code>` (upgrade guide 4.23, lines 1668-1672).
- **C:** a backtick followed by `"` is read as a curved-quote marker, so the
monospace span cannot close (camel-jbang-mcp.adoc:189).
Fixes:
- **A and B:** use literal monospace, `` `+mail.smtp.*+` ``.
- **C:** use real curly quotes or double backticks.
- **Avoid** `` `Camel\*` ``. It keeps the HTML valid but silently leaves a
later `*bold*` unrendered.
Applying these to copies of all 35 sources makes every page pass.
<details>
<summary>Source locations by repository (branch heads as of
2026-09-13)</summary>
| Repo | Source: lines | Published pages | Pattern |
|---|---|---|---|
| apache/camel | `docs/user-manual/modules/ROOT/pages/security-model.adoc`
main: 231, 322, 326, 425, 431, 432, 622, 651, 680-692, 1024, 1097, 1121, 1122,
1182, 1186, 1466, 1468, 1472 | manual/security-model | A |
| | `…/camel-jbang-mcp.adoc` main: 189 | manual/camel-jbang-mcp | C |
| | `…/camel-jbang-tui.adoc` main: 177, 203, 204 | manual/camel-jbang-tui |
A |
| | `…/camel-4x-upgrade-guide-4_14.adoc` main: 1050, 1055, 1266-1268 |
manual 4_14 | A |
| | `…/camel-4x-upgrade-guide-4_18.adoc` main: 636, 1397, 1402, 1805-1807 |
manual 4_18 | A |
| | `…/camel-4x-upgrade-guide-4_19.adoc` main: 326, 328, 352 | manual 4_19 |
A |
| | `…/camel-4x-upgrade-guide-4_21.adoc` main: 411, 413, 430, 431, 449, 450,
1021, 1026, 1082, 1083, 1488-1490, 2157, 2160, 2241 | manual 4_21 | A |
| | `…/camel-4x-upgrade-guide-4_22.adoc` main: 1946, 1947 | manual 4_22 | A |
| | `…/camel-4x-upgrade-guide-4_23.adoc` main: 703, 1040, 1041, 1656, 1659,
1668, 1671, 1672 | manual 4_23 | A, B |
| | `components/camel-mail/src/main/docs/mail-component.adoc` 4.18.x: 594,
600; 4.22.x and main: 902, 908 | components/{4.18.x,4.22.x,next}/mail-component
| A |
| | `components/camel-leveldb/src/main/docs/leveldb.adoc` 4.18.x: 79, 80,
84; 4.22.x: 77, 78, 82 | components/{4.18.x,4.22.x}/others/leveldb | A |
| | `components/camel-ai/camel-ai-tool/src/main/docs/ai-tool-component.adoc`
4.22.x: 150; main: 150, 202, 235 | components/{4.22.x,next}/ai-tool-component |
A |
| | `components/camel-ai/camel-mcp-server/src/main/docs/mcp-server.adoc`
4.22.x: 51, 53, 123, 124; main: 54, 56, 166, 167 |
components/{4.22.x,next}/others/mcp-server | A |
| | `components/camel-mdc/src/main/docs/mdc.adoc` 4.22.x and main: 73, 74 |
components/{4.22.x,next}/others/mdc | A |
| | `dsl/camel-yaml-dsl/camel-yaml-dsl/src/main/docs/yaml-dsl.adoc` 4.22.x
and main: 840 | components/{4.22.x,next}/others/yaml-dsl | A |
| | `components/camel-opa/src/main/docs/opa-component.adoc` main: 183 |
components/next/opa-component | A |
| apache/camel-quarkus |
`docs/modules/ROOT/pages/migration-guide/3.39.0.adoc` main: 42; `…/3.33.3.adoc`
3.33.x: 148 | migration-guide/3.39.0, 3.33.3 | A |
| |
`extensions/jolokia/runtime/src/main/java/org/apache/camel/quarkus/jolokia/config/JolokiaRuntimeConfig.java:90-91`
(Javadoc, generates `reference/extensions/jolokia.adoc`) | extensions/jolokia
{next,3.33.x} | A |
| |
`extensions/micrometer/runtime/src/main/java/org/apache/camel/quarkus/component/micrometer/CamelMicrometerConfig.java:117-118`
(Javadoc) | extensions/micrometer next | A |
| | `extensions/mcp-server/runtime/src/main/doc/usage.adoc:38, 40` |
extensions/mcp-server next | A |
| apache/camel-spring-boot |
`components-starter/camel-micrometer-starter/src/main/java/.../springboot/metrics/CamelMetricsConfiguration.java`
main: 105-106; 4.22.x: 104-105 (Javadoc, generates `starters/micrometer.adoc`)
| starters/micrometer {next,4.22.x} | A |
| apache/camel-kamelets | `docs/modules/ROOT/pages/security-model.adoc` main
and 4.22.x: 298, 299, 385, 400 | security-model {next,4.22.x} | A |
| apache/camel-kafka-connector |
`docs/modules/ROOT/pages/security-model.adoc` main: 80-82 | security-model next
| A |
| apache/camel-karaf | `docs/modules/ROOT/pages/security-model.adoc` main:
201, 202 | security-model 4.9.x | A |
For the three Javadoc sources, fix the Java comment, not the generated
`.adoc`. In camel-spring-boot a `+…+` passthrough would also show up literally
in the Spring configuration-metadata tooltip, so rewording the Javadoc may be
better there.
</details>
_Claude Code on behalf of Adriano Machado (@ammachado)_
_This was generated by an AI agent and may contain inaccuracies. Please
verify before relying on it._
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
