turn the docs your agent writes into something worth reading.
a small rust cli + claude code skill that renders plain markdown to polished, self-contained html — with a structured "visuals" sidecar for the cases where prose alone isn't enough.
agents now write the docs. humans review them. markdown was designed for humans writing for humans — when one end becomes an agent, the equilibrium breaks: claude generates 500-line specs nobody reads past line 100, ascii diagrams that look terrible, and .md files browsers don't render. glyph's bet: keep markdown source pure, push structured visual data to a sidecar, and ship a renderer that produces an html artifact as good as the hand-written kind.
cargo install --git https://github.com/rohansx/glyph glyph-clifor diagrams (mermaid passthrough in v0.1):
npm i -g @mermaid-js/mermaid-cliglyph init # in your project root
glyph render examples/cloakpipe-roadmap.md
glyph watch examples/ # rebuild on save
glyph visuals --schema grid # canonical json schema for any visualwhat glyph init installs:
glyph.toml— project config.glyph/themes/and.glyph/components/— extension points.claude/skills/glyph/SKILL.md— the claude code skill that auto-triggers on doc prompts
per document, two source files:
roadmap.md ← human-readable prose (pure markdown + admonitions)
roadmap.glyph.yaml ← structured visuals (auto-managed by claude)
renders to a single self-contained roadmap.html. the markdown stays pure — visual references are just github admonitions:
## go-to-market
we considered three approaches.
> [!visual] go-to-market-comparison
direct enterprise sales were rejected for the long cycles. b2b2b through
ai companies was selected because they own the regulated-industry
relationships and we provide the rails.
> [!risk]
> venice may push back on revenue share. prepare flat-fee fallback.the sidecar holds the structured part:
visuals:
go-to-market-comparison:
type: grid
cols: 3
cards:
- title: direct enterprise
badge: rejected
body: long sales cycles, requires soc2
- title: b2b2b via ai companies
badge: selected
body: ai cos own the relationships, we provide the rails
- title: oss-only
badge: rejected
body: no revenue pathclaude edits prose by editing markdown, edits visuals by editing yaml. cross-cutting changes (renaming a visual referenced in prose) touch both, but that's the only case both files change at once. matches the html / css / js separation every codebase already uses.
| type | purpose |
|---|---|
grid |
comparison cards with optional badges |
diagram |
flow / sequence / state — via mermaid passthrough in v0.1, native svg in v0.2 |
diff |
inline syntax-highlighted diffs (v0.2) |
data |
structured tables (v0.2) |
island |
scoped interactive html widgets (v0.2) |
callouts (> [!note], > [!warning], > [!risk], > [!tip]) need no sidecar — they're styled directly from the github-admonition syntax.
| viewer | what they see |
|---|---|
| github web | full markdown render. > [!visual] name shows as a hinted callout. |
chrome opening the rendered .html |
full polished render — the canonical path |
cmd+p from the html |
clean printed pdf |
| slack/discord paste | markdown body renders; visual markers show as plain quoted text |
the .md is the editable source. the .html is the canonical artifact. the sidecar is for claude. no viewer needs to learn glyph — the rendered html is just html.
examples/cloakpipe-roadmap.md— marquee example: grid + flow diagram + state diagram + calloutsexamples/pr-explainer.md— pr writeup: diff + sequence diagramexamples/architecture-review.md— meta example: flow diagram + grid + data table
each pair is a .md + .glyph.yaml. point glyph render at any of them.
| read | for |
|---|---|
| docs/product-overview.md | what glyph is, the problem, the audience, why ship it |
| docs/architecture.md | crates, pipeline, cli surface, full glyph.toml |
| docs/visual-spec.md | sidecar schemas, when-to-use rules, the SKILL.md |
| docs/phases.md | v0.1 / v0.2 / v0.3 / post-launch + decisions log |
| docs/plan.md | shipping order, vertical slices |
| docs/risks.md | failure modes ranked, with mitigations |
| docs/spec.md | original spec, source of truth |
v0.1. ships the markdown-to-html pipeline, default theme, three visual types (grid + diagram + callout-via-admonitions), the claude code skill, sticky toc, syntax highlighting, sidecar resolution, and the cli (init, render, watch, visuals --schema).
up next (v0.2): native svg diagram renderer, full visual catalog (diff / data / island), glyph lint, glyph squash / unsquash / extract, pdf output, prose-mirror requirement in the skill, .txt.md rag projection.
see docs/phases.md for the full roadmap.
- fork the repo
cargo test --workspaceshould pass- follow the conventions in docs/architecture.md
- open a pr
MIT