haiku + docs-page: nav-link 缺 display:block, mermaid block 被 <pre> 包裹导致 syntax error

[xiataoyue]

Environment

• Agent CLI: Claude Code (/Users/naughtybeds/.local/bin/claude)
• Model: claude-haiku-4-5-20251001
• Template: docs-page
• html-anything: main @ commit fresh clone (2026-05-26)
• Input: ~3KB markdown with one mermaid sequenceDiagram

Bug 1 — .nav-link 缺少 display: block

In the generated HTML, the left-sidebar nav block looks like:

<aside class="...">
  <div class="mt-3 space-y-1">
    <a href="#overview" class="nav-link active">概览与索引</a>
    <a href="#fig1" class="nav-link">图1：启动连接</a>
    ...
  </div>
</aside>

with this CSS:

.nav-link {
    padding: 0.625rem 1rem;
    color: var(--color-text-muted);
    text-decoration: none;
    border-radius: 0.375rem;
    transition: all 0.2s;
    font-size: 0.9375rem;
    /* ❌ no display: block — anchors stay inline */
}

Result: every nav item collapses onto one wrapped line; space-y-1 is a no-op for inline <a> (it adds margins to direct children, but inline elements don't honor vertical margins).

Fix (one line): add display: block; (or use Tailwind class block on the <a> instead of a custom class).

Reproducibility: consistent across multiple haiku runs of docs-page. A second haiku run with same input did emit display: block correctly — so this is an output-stability issue with the model on this template, not deterministic.

Bug 2 — mermaid block wrapped in <pre> and <br/> tags get eaten

The same haiku run produced:

<div class="mermaid">
    <pre>
sequenceDiagram
    autonumber
    participant App as "App (client.c)"
    App->>Lib: wl_display_connect(NULL)<br/>wayland-client.c:1351
    ...
    </pre>
</div>

Two problems:

1. <pre> wrapper: Mermaid's init reads <div class="mermaid"> textContent. Browser HTML parsing strips the <pre> start/end tags (they end up empty whitespace), but more importantly the <br/> tags inside are parsed as real <br> elements and don't appear in textContent — they're replaced by a literal newline. Mermaid then sees wl_display_connect(NULL)\nwayland-client.c:1351 as the message text, which is invalid syntax inside a single App->>Lib: … line. Result: "Syntax error in text — mermaid version 10.9.6".

2. <br/> should be HTML-entity-encoded so mermaid receives the literal string <br/> and applies its own line-break rendering.

Fix: in the mermaid output path, render as:

<div class="mermaid">
sequenceDiagram
    autonumber
    participant App as "App (client.c)"
    App->>Lib: wl_display_connect(NULL)&lt;br/&gt;wayland-client.c:1351
</div>

No <pre>, <br/> → <br/>. This works correctly when the agent emits it.

Suggested guardrails in SKILL.md

Adding these two lines to next/src/lib/templates/skills/docs-page/SKILL.md (and possibly shared.ts) would likely eliminate both bugs:

- 任何 .nav-link / .sidebar-item / 自定义类 ➜ 必须含 `display: block` 或同等 `flex`，否则在 sidebar 中会塌成一行。
- Mermaid 块直接写 `<div class="mermaid">…</div>`，**不要嵌套 `<pre>`**；图源里的 `<br/>` 必须 HTML-entity 编码为 `&lt;br/&gt;`。

Repro repo / context

I'm running html-anything against a real markdown doc that contains 5 Mermaid sequence/class diagrams generated from a codebase analysis. Happy to share the input markdown if useful — the bugs are deterministic on this template + this CLI; one fresh haiku run reproduces both.

Thanks for the project! Local agent → HTML loop is a great direction. 🚀

[lefarcen]

This is open for community help.

If you'd like to work on it, comment /claim below. The first /claim after the latest release gets it. Any comment, linked PR, or progress note keeps the claim active.

[lefarcen]

Hi @xiataoyue — thanks for the very concrete repro and the suggested guardrails. 👀

I checked the current docs-page skill and shared template directives: the sample HTML already uses block sidebar links (.sidebar a { display: block; ... }), but the skill prompt does not explicitly require that when the model emits custom .nav-link / sidebar classes. I also don't see Mermaid-specific guidance in the shared directives, so your proposed div.mermaid / no nested <pre> / <br/> rule looks like the right direction.

I've labeled this as a scoped bug and community-friendly fix. A good patch would likely add those constraints to next/src/lib/templates/skills/docs-page/SKILL.md and consider whether the Mermaid rule belongs in next/src/lib/templates/shared.ts so other templates benefit too. If you're able to share a minimal markdown sample that reproduces the Mermaid failure, that would help us turn this into a regression case instead of only a prompt guardrail.

[xiataoyue]

Hi @lefarcen — thanks for the quick triage! Sharing the minimal repro below.

Minimal repro (bug-88-repro.md)

# Wayland connect sequence

Reproduces both bugs when run through `docs-page` with `haiku`.

```mermaid
sequenceDiagram
    participant App
    participant Lib as libwayland-client
    App->>Lib: wl_display_connect(NULL)<br/>wayland-client.c:1351
    Lib-->>App: struct wl_display*
```

- item one
- item two
- item three

Steps

1. node convert.mjs --in=bug-88-repro.md --template=docs-page --model=haiku (small SSE client wrapping /api/convert; happy to share)
2. Open the generated HTML in a browser

Observed (haiku run 1)

• Mermaid block wrapped in <div class="mermaid"><pre>…</pre></div> → "Syntax error in text"
• Custom .nav-link class missing display: block → sidebar items collapse to one line

Observed (haiku run 2, same input)

• display: block correctly emitted → non-deterministic prompt-stability bug

Interestingly, the sonnet output for the same input uses a different (robust) pattern: it puts diagram sources in a JS string and does pre.textContent = source at runtime, which bypasses the <br/>-eaten-by-parser issue entirely. So the prompt could either (a) forbid the broken pattern or (b) suggest the robust pattern explicitly.

Patch sketch

next/src/lib/templates/shared.ts (Mermaid handling is template-agnostic, belongs in SHARED_DESIGN_DIRECTIVES):

+ - Mermaid 块: 直接 `<div class="mermaid">…</div>`, 不要嵌套 `<pre>`;
+   块内的 `<br/>` 必须 HTML-entity 编码为 `&lt;br/&gt;` 才能被 mermaid 正确换行。
+   推荐(更稳健): 用 `<pre class="mermaid">` 占位 + JS `pre.textContent = source` 注入,
+   绕开浏览器对 `<br/>` 等标签的解析。

next/src/lib/templates/skills/docs-page/SKILL.md:

+ - Sidebar / TOC 链接类(.nav-link / .sidebar-link / .toc-link 等):
+   必须含 `display: block`(或 Tailwind `block` 工具类), 否则 `space-y-*` 在 inline `<a>`
+   上无效, 链接会塌成一行。

Happy to open a PR with the diff + a small e2e regression that runs the repro through haiku and asserts (a) sidebar <a> elements are block-level in computed style and (b) no <pre> is nested inside .mermaid containers. Let me know if that scope sounds right and I'll claim the issue.

[lefarcen]

Hey @xiataoyue, this is exactly the repro shape we needed — thank you.

That PR scope sounds right to me. One small adjustment: I’d avoid making CI depend on a live haiku run unless the repo already has a deterministic agent stub for it; the two-run behavior you found is useful evidence, but it could make the regression flaky. A solid PR would be:

• add the Mermaid guidance to SHARED_DESIGN_DIRECTIVES in next/src/lib/templates/shared.ts, preferably steering models toward the robust textContent injection pattern you described;
• add the sidebar link rule to next/src/lib/templates/skills/docs-page/SKILL.md;
• add a deterministic regression check if practical — for example, asserting the assembled prompt contains these guardrails, plus any fixture/browser assertion that does not rely on a live model call.

If you want to take it, please comment /claim so the issue is reserved for you, then open the PR when ready. Happy to review it.

[xiataoyue]

/claim

Sounds good — agreed on dropping the live-model assertion. Plan:

1. next/src/lib/templates/shared.ts — append Mermaid textContent-injection guidance to SHARED_DESIGN_DIRECTIVES. Steers models toward the robust <pre class="mermaid"> + pre.textContent = source pattern (the path I observed in sonnet output), with the <br/> entity rule as a fallback for the direct-<div class="mermaid"> form.

2. next/src/lib/templates/skills/docs-page/SKILL.md — add the sidebar-link display: block constraint.

3. Tests (deterministic only) —

   • Unit test on assemblePrompt() asserting the returned prompt contains the two new directives (substring match against the shared directives + docs-page body).
   • Optional small jsdom fixture: a representative HTML snippet of the broken haiku output (nested <pre> in .mermaid + missing display: block) loaded in a test renderer, asserting (a) computed style of sidebar <a> is block and (b) no <pre> is nested inside .mermaid. Will only add this second piece if it fits cleanly into the existing test setup; otherwise just the unit assertion.

Will open the PR within a few days.

[lefarcen]

Claimed by @xiataoyue. Thanks for picking this up! 🎉

Quick question to time check-ins right — roughly how long do you think this will take?

• A few hours / today
• 1-3 days
• ~ 1 week
• Longer / unsure

Reply with whatever fits. If you don't reply, I'll default to checking in every ~12h. Either way, any comment, linked PR, or progress note keeps the claim active.

[lefarcen]

Hey @xiataoyue, PR #91 is now open for the prompt guardrails we discussed here.

It targets the two observed output-stability failures from this issue: Mermaid source should avoid the nested <pre> / raw <br/> parsing trap, and docs-page sidebar/TOC links should be forced to render as block/flex items so space-y-* can create vertical spacing. Keeping this issue open while #91 goes through review, then we can verify/close once the fix lands.

[lefarcen]

Thanks @xiataoyue — the plan you wrote here matches what landed in PR #91, including the deterministic prompt-guardrail tests and no live-model CI dependency.

I’ll keep detailed review feedback on the PR so the discussion stays in one place. Leaving this issue open while #91 is reviewed; once that PR lands, we can verify and close this out.