/teach: Improve guidance for tree/hierarchy diagrams in HTML explainers
# Improve guidance for tree/hierarchy diagrams in HTML explainers
First off — the `/teach` skill is fantastic. The philosophy of knowledge → skills → wisdom, the zone of proximal development framing, and the HTML explainer approach are all brilliantly thought out. Thank you for open-sourcing this.
## The Problem
When the AI generates an HTML explainer that includes a tree or hierarchy diagram, it tends to produce a mix of ASCII art tree characters (`├──`, `│`, `└──`) with inline HTML `<span>` elements for styling. This looks something like:
```html
<div class="diagram">
<span class="node">Document</span><br>
├── <span class="node">Paragraph</span><br>
│ ├── Text: "这是一个"<br>
│ ├── Text: "加粗" <span class="mark">[Bold]</span><br>
│ ├── Text: "和"<br>
│ └── Text: "斜体" <span class="mark">[Italic]</span><br>
│<br>
└── <span class="node">Heading</span> <span class="label">(level: 2)</span><br>
└── Text: "二级标题"
</div>
```
When rendered in a browser with a proportional font, the alignment completely breaks — tree lines don't line up, indentation is inconsistent, and the diagram becomes unreadable.
<img width="852" height="314" alt="Image" src="https://github.com/user-attachments/assets/bb42cc0e-ccd3-422c-a0db-c4a285f3a94d" />
## Root Cause
ASCII tree diagrams rely on precise character-width alignment, which only works in monospace contexts. The current SKILL.md doesn't provide guidance on how to represent hierarchical or tree structures in HTML explainers, so the AI falls back to mixing ASCII art with HTML — the worst of both worlds.
## Suggested Improvements
### Short-term: Wrap ASCII trees in `<pre><code>`
If the AI chooses to use ASCII tree diagrams, they should be wrapped in a monospace container:
```html
<pre><code>
Document
├── Paragraph
│ ├── Text: "这是一个"
│ ├── Text: "加粗" [Bold]
│ ├── Text: "和"
│ └── Text: "斜体" [Italic]
└── Heading (level: 2)
└── Text: "二级标题"
</code></pre>
```
This preserves alignment but sacrifices the ability to use `<span>` styling on individual nodes.
### Long-term: Use semantic HTML for tree structures
A better approach is to use nested HTML lists with CSS for tree lines, which works with any font and supports rich styling:
```html
<ul class="tree">
<li><span class="node">Document</span>
<ul>
<li><span class="node">Paragraph</span>
<ul>
<li>Text: "这是一个"</li>
<li>Text: "加粗" <span class="mark">[Bold]</span></li>
<li>Text: "和"</li>
<li>Text: "斜体" <span class="mark">[Italic]</span></li>
</ul>
</li>
<li><span class="node">Heading</span> <span class="label">(level: 2)</span>
<ul>
<li>Text: "二级标题"</li>
</ul>
</li>
</ul>
</li>
</ul>
```
With appropriate CSS (e.g., `list-style: none`, `padding-left`, and `::before`/`::after` pseudo-elements for tree lines), this produces a clean, responsive, and stylable tree diagram.
## Proposed SKILL.md Addition
Consider adding guidance under the "Acquiring Knowledge" section, something like:
> When representing hierarchical or tree structures in HTML explainers, use semantic HTML (nested lists with CSS) instead of ASCII art. If ASCII art is necessary, always wrap it in `<pre><code>` to ensure monospace alignment. Never mix ASCII tree characters with inline HTML styling outside of a `<pre>` block.
Thanks again for the great work on this skill!
0 条评论