Skip to content

docs(python-architect): document mermaid classDiagram :::cssClass GitHub-render trap #970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danielmeppiel merged 2 commits into from
Apr 27, 2026
Merged

docs(python-architect): document mermaid classDiagram :::cssClass GitHub-render trap #970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fcb9a22
docs(python-architect): document mermaid classDiagram :::cssClass Git…
danielmeppiel Apr 26, 2026
4bfbe77
Merge branch 'main' into fix/python-architect-mermaid-gotcha
danielmeppiel Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .apm/agents/python-architect.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,16 @@ classDiagram
Read the PR's diff and surrounding code, then draw the actual
problem-space classes.)

**Mermaid `classDiagram` GitHub-render gotcha**: the `:::cssClass`
shorthand is ONLY valid as a standalone `class Name:::cssClass`
declaration (or inside a `class Name:::cssClass { ... }` block).
GitHub's mermaid parser rejects `:::cssClass` appended to a
relationship line (`A *-- B:::touched`) with `Expecting 'NEWLINE',
'EOF', 'LABEL', got 'STYLE_SEPARATOR'`. Always declare the styled
classes on their own lines BEFORE the `classDef` block. This trap
does not apply to `flowchart` diagrams, where the inline form is
valid.

If the PR is purely procedural (no class changes anywhere in scope),
state that explicitly and substitute a `classDiagram` showing the
module boundaries and the function entry points -- still annotated
Expand Down
10 changes: 10 additions & 0 deletions .github/agents/python-architect.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,16 @@ classDiagram
Read the PR's diff and surrounding code, then draw the actual
problem-space classes.)

**Mermaid `classDiagram` GitHub-render gotcha**: the `:::cssClass`
shorthand is ONLY valid as a standalone `class Name:::cssClass`
declaration (or inside a `class Name:::cssClass { ... }` block).
GitHub's mermaid parser rejects `:::cssClass` appended to a
relationship line (`A *-- B:::touched`) with `Expecting 'NEWLINE',
'EOF', 'LABEL', got 'STYLE_SEPARATOR'`. Always declare the styled
classes on their own lines BEFORE the `classDef` block. This trap
does not apply to `flowchart` diagrams, where the inline form is
valid.

If the PR is purely procedural (no class changes anywhere in scope),
state that explicitly and substitute a `classDiagram` showing the
module boundaries and the function entry points -- still annotated
Expand Down
2 changes: 1 addition & 1 deletion apm.lock.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ local_deployed_file_hashes:
.github/agents/doc-analyser.agent.md: sha256:47b1d0204904b786c19d4fe84343e86cdab6f92f862f676ba741ffe6e1385679
.github/agents/doc-writer.agent.md: sha256:328a5b9ea079869b8ccd914a6e2135c204225a5eedb42f59a1ec73058f7f0b47
.github/agents/oss-growth-hacker.agent.md: sha256:8d18f5be46913c40ad3aa66fb984575a88988cfac402d39353cdfb09f7e582c5
.github/agents/python-architect.agent.md: sha256:32ed3390cb0e41fea28b3fd95b00124cd097ea0db51f992d2349e6837742723c
.github/agents/python-architect.agent.md: sha256:a70b1be6cd877a85414a65a1db8117be7dbecc3865d98045f46ed14462fda099
.github/agents/supply-chain-security-expert.agent.md: sha256:9a4e731b12e7658f71d54c22e90f80ce0c45e3eacbb069b8505ed96ec9e79ba5
.github/instructions/changelog.instructions.md: sha256:1e51ec4c74e847967962bd279dc4c6e582c5d3578490b3c28d5f3acd3e05f73e
.github/instructions/cicd.instructions.md: sha256:9c0fafc74f743aa97e5adba2168d66c9e3a327b135065e3b804bdbb5f04cda5d
Expand Down
Loading