HTML Style Guide
HTML Style Guide
How to author
html_content for pal-e-docs notes. Notes are HTML fragments rendered inside a Jinja2 template shell (base.html) with shared CSS. This guide ensures consistent, readable output across all agents and humans.Allowed Elements
| Element | Use for | Notes |
|---|---|---|
| <code><h2></code> | Note title / major sections | Styled at 1.25rem inside <code>.note-content</code>. Use as the top-level heading in note content. |
| <code><h3></code> | Subsections | Used for template section matching. Templates validate by checking <code><h3></code> headings. |
| <code><h4></code> | Sub-subsections | Use sparingly — within phases of plans or subsections of large notes. |
| <code><p></code> | Prose paragraphs | Styled with 0.5rem vertical margin. |
| <code><ul></code>, <code><ol></code> | Lists | Indented with 1.5rem left margin. |
| <code><li></code> | List items | 0.25rem vertical margin. |
| <code><table></code> | Structured data, comparisons, matrices | Use <code><th></code> for header cells. |
| <code><code></code> | Inline code, slugs, commands, variable names | Light gray background (#f0f0f0), 3px border-radius, 0.9em font-size. |
| <code><pre><code></code> | Code blocks | For multi-line code snippets. |
| <code><pre class="mermaid"></code> | Mermaid diagrams | Auto-rendered by mermaid.js. See <code>mermaid-authoring</code> convention. |
| <code><strong></code> | Bold emphasis | For key terms, labels in lists. |
| <code><em></code> | Italic emphasis | For asides, clarifications. |
| <code><a href="..."></code> | External links | Blue (#0366d6), underline on hover. For internal note references, use inline <code><code>slug</code></code> instead. |
Structure Patterns
Standard note structure
Decision table
Roadmap / checklist
CSS Classes Available in base.html
These classes are defined in
base.html and available in the browse frontend:| Class | Purpose | Use in notes? |
|---|---|---|
| <code>.badge</code> | Status/platform badge base | Rarely — in project page repo tables |
| <code>.badge-github</code> | Dark badge for GitHub | In repo tables |
| <code>.badge-forgejo</code> | Green badge for Forgejo | In repo tables |
| <code>.badge-active</code> | Green badge for active status | In repo tables |
| <code>.badge-archived</code> | Gray badge for archived | In repo tables |
| <code>pre.mermaid</code> | Mermaid diagram block | Yes — see <code>mermaid-authoring</code> |
Other classes (
.tag, .meta, .section, .card-grid, .card, .doc-list) are used by Jinja2 templates, not by note content directly.What NOT to Do
- Don't use inline
style=""attributes — all styling comes frombase.html - Don't use
<div>for layout — stick to semantic HTML - Don't use
<h1>— the page template provides the h1 from the note title - Don't use
<img>— no image hosting; use mermaid for diagrams - Don't use
<script>— security risk, especially when notes go public - Don't add CSS classes that don't exist in
base.html— they'll be silently ignored
XSS Note
Note content is rendered with
| safe in Jinja2 — no sanitization. Fine for internal use (trusted agents/humans). HTML sanitization must be added before notes go public via Tailscale Funnel.Related
mermaid-authoring— mermaid diagram conventionnote-conventions— slug naming, tagging, and linking conventions