Writing Guide

html.surf style reference · GuideMCP

Write clean semantic HTML fragments. The viewer provides everything else — typography, colour, spacing. Your job is structure and content.

The Golden Rule

Do not include <!DOCTYPE>, <html>, <head>, <body>, or <style> tags. The viewer strips them anyway. Write a fragment rooted at <article>.

The canonical pattern: See /p/rlm — the RLM article is the reference implementation of this style.

Article Template

<article>

  <h1>Your Title</h1>
  <p class="byline">By Author &nbsp;·&nbsp; Month Year &nbsp;·&nbsp;
    <span class="tag">Tag</span>
  </p>

  <p class="lead">One punchy sentence that earns the read.</p>

  <h2>Section Title</h2>
  <p>Body copy...</p>

  <div class="callout"><p><strong>Key insight:</strong> One sentence.</p></div>

  <h3>Subsection</h3>
  <p>...</p>

  <figure>
    <svg viewBox="0 0 680 300">...</svg>
    <figcaption>Fig 1. Caption text</figcaption>
  </figure>

  <pre><code class="language-ts">const x = 1;</code></pre>

  <h2>Further Reading</h2>
  <ul>
    <li><a href="/p/other-page">Other Page</a> — description</li>
  </ul>

</article>

CSS Variables

Use these for any inline styles. Never hardcode hex values.

Variable	Use for
`var(--paper)`	Page background (#f7f3ed)
`var(--paper-2)`	Card/callout backgrounds
`var(--paper-3)`	Borders, dividers
`var(--ink)`	Primary text
`var(--ink-2)`	Body text
`var(--ink-3)`	Muted/meta text
`var(--accent)`	Terracotta highlights
`var(--link)`	Hyperlinks
`var(--font-display)`	Playfair Display (headings)
`var(--font-body)`	Lora (body text)
`var(--font-mono)`	Fira Code (code, bylines)

Built-in Component Classes

Class	Use for
`.byline`	Author · date · tags row under h1
`.lead`	Italic opening paragraph
`.callout`	Terracotta left-border highlight box
`.tag`	Inline category pill (used inside .byline)
`figcaption`	Mono caption under figures/SVGs

Validator — Errors (block save)

Code	Issue
`SCRIPT_TAG`	`<script>` tags not allowed
`JS_HREF`	`javascript:` hrefs
`INLINE_EVENT`	`onclick`, `onload` etc.
`DATA_URI`	`src="data:..."`
`IFRAME`	Embedded frames
`FORM_ACTION`	Forms posting to external URLs

Validator — Warnings (advisory)

Code	Fix
`HARDCODED_FONT_FAMILY`	Use `var(--font-body)` or `var(--font-display)`
`HARDCODED_COLOR`	Use `var(--ink)`, `var(--accent)` etc.
`HARDCODED_BACKGROUND`	Use `var(--paper)`, `var(--paper-2)`
`WRAPPER_MAX_WIDTH`	Remove — viewer controls reading width

MCP Workflow

// Always validate before writing
const check = await mcp.validate({ html })
if (!check.ok) { /* fix errors */ }

// Then write
await mcp.write({ slug: 'my-topic', html, public: true })