From 7d48bd0367185e83108aae8fb013af74bed48638 Mon Sep 17 00:00:00 2001
From: shankar0123 <skreddy040@gmail.com>
Date: Mon, 4 May 2026 02:43:47 +0000
Subject: [PATCH] docs(intermediate-ca-hierarchy): fix stateDiagram-v2 GitHub
 render parse error
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GitHub's mermaid renderer (older version) doesn't accept <br/> tags
or em-dashes in stateDiagram-v2 transition labels. The conversion
shipped in 85649cf used both, which the GitHub markdown view rejects
with:

  Parse error on line 6: ...ding for<br/>already-issued leaves until
                         -----------------------^
  Expecting 'SPACE', 'NL', 'DESCR', '-->', ... got 'INVALID'

(flowchart and sequenceDiagram tolerate <br/> + em-dashes inside
labels — only stateDiagram-v2 trips.)

Fix: shorten transition labels to single-line ASCII and move the
long-form descriptions into 'note right of <state>' blocks. Same
information, renders cleanly on GitHub.

  active --> retiring : Retire(confirm=false)
  retiring --> retired : Retire(confirm=true)
  retired --> [*]

  note right of retiring
      Drain start. CA stops issuing
      NEW children; existing children
      keep issuing until they retire.
  end note

  note right of retired
      Terminal. Refused if active children
      remain (ErrCAStillHasActiveChildren
      → HTTP 409). OCSP keeps responding
      for already-issued leaves until expiry.
  end note

Verified locally:
  Other mermaid blocks added in the audit pass (sequenceDiagram +
    flowchart TD) keep their <br/> + em-dashes — those don't trip
    GitHub's renderer. Only stateDiagram-v2 needed the fix.
  No content lost. The note blocks carry every fact the old
    multi-line transition labels had.

Doc-only commit.
---
 docs/intermediate-ca-hierarchy.md | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/intermediate-ca-hierarchy.md b/docs/intermediate-ca-hierarchy.md
index eef7e3c..7fa7689 100644
--- a/docs/intermediate-ca-hierarchy.md
+++ b/docs/intermediate-ca-hierarchy.md
@@ -47,9 +47,22 @@ reference can leak.
 stateDiagram-v2
     [*] --> created : CreateRoot / CreateChild
     created --> active : registration completes
-    active --> retiring : Retire(confirm=false) —<br/>drain start; this CA stops issuing<br/>NEW children but existing children continue
-    retiring --> retired : Retire(confirm=true) —<br/>terminal; refused if active children remain<br/>(ErrCAStillHasActiveChildren → HTTP 409)
-    retired --> [*] : no issuance;<br/>OCSP keeps responding for<br/>already-issued leaves until expiry
+    active --> retiring : Retire(confirm=false)
+    retiring --> retired : Retire(confirm=true)
+    retired --> [*]
+
+    note right of retiring
+        Drain start. CA stops issuing
+        NEW children; existing children
+        keep issuing until they retire.
+    end note
+
+    note right of retired
+        Terminal. Refused if active children
+        remain (ErrCAStillHasActiveChildren
+        → HTTP 409). OCSP keeps responding
+        for already-issued leaves until expiry.
+    end note
 ```
 
 Drain-first semantics: a CA in `retiring` state cannot terminalize to