Skip to content

fix(archie): use 4-backtick fence in comment template to avoid literal backslashes in Mermaid blocks - #381

Open
xpepper wants to merge 1 commit into
githubnext:mainfrom
xpepper:fix/archie-mermaid-nested-fences
Open

fix(archie): use 4-backtick fence in comment template to avoid literal backslashes in Mermaid blocks#381
xpepper wants to merge 1 commit into
githubnext:mainfrom
xpepper:fix/archie-mermaid-nested-fences

Conversation

@xpepper

@xpepper xpepper commented Sep 6, 2026

Copy link
Copy Markdown

Problem

In workflows/archie.md, the "Comment Structure" example prompt currently uses backslash escapes on nested Mermaid fences (\```mermaid / \```) inside a standard 3-backtick ```markdown code block:

### Comment Structure

```markdown
## 📊 Mermaid Diagram Analysis

*Generated by Archie for @${{ github.actor }}*

### [Diagram 1 Title]

[Brief description of what this diagram shows]

\```mermaid
[diagram code]
\```
```

Because gh-aw injects the workflow Markdown directly into the agent's prompt context at runtime, the LLM receives literal \```mermaid. The LLM frequently copies this formatting verbatim into its output comments.

Under GitHub Flavored Markdown (CommonMark), a backslash before backticks is treated as a character escape. The fence is parsed as a plain paragraph (<p>```mermaid ...</p>) rather than a <div class="highlight highlight-source-mermaid"> block, causing GitHub to render literal text instead of an interactive Mermaid diagram.

Solution

Per CommonMark Spec §4.5, an outer code block with $N$ backticks can contain inner code blocks of $N-1$ backticks without escaping.

  • Wrap the outer template block in 4 backticks (````markdown ... ````).
  • Use clean, standard 3-backtick ```mermaid and ``` fences inside.

This delivers clean, idiomatic Mermaid blocks in the model's prompt with zero backslashes, ensuring generated issue/PR comments render diagrams properly on GitHub.

Copilot AI lite review requested due to automatic review settings September 6, 2026 07:49

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The change is a small, correct Markdown fencing fix that aligns the example with CommonMark/GFM behavior and has no apparent side effects.

Pull request overview

Updates the Archie workflow documentation template so Mermaid code fences in the “Comment Structure” example render correctly when copied into GitHub comments (and when injected into the agent prompt), avoiding backslash-escaped fences that break Mermaid rendering under CommonMark/GFM.

Changes:

  • Switches the outer example block to a 4-backtick fenced code block (markdown … ) so inner triple-backtick Mermaid fences can be included unescaped.
  • Replaces \```mermaid / ```` with standard mermaid / inside the example template.
File summaries
File Description
workflows/archie.md Adjusts the documentation prompt template to use a 4-backtick outer fence so Mermaid blocks can be shown without backslash escapes.
Review details
  • Files reviewed: 1/1 changed files
  • Comments generated: 0
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants