agnes-the-ai-analyst/docs/operator/news-content-guide.md

News content authoring guide

This page documents the HTML vocabulary the /home news perex and /news permalink page recognise. Authors should write content using only these allowed tags, attributes, and class names — anything outside the list is silently stripped on save.

Where the content lives

A single news entity (intro + content) is stored in DuckDB table news_template. Every save creates / updates a row with a monotonically increasing version. The latest row with published = TRUE is what /home and /news render. The admin can roll back by unpublishing a newer version (web falls back to the next-highest published version automatically).

Drafts older than 30 days that were never published, and superseded published versions older than 30 days, are pruned on save. The currently-displayed published version is never pruned regardless of age.

How to author

Two equivalent surfaces:

• Web admin UI: /admin/news — two textareas (intro + full content) with a sandboxed live preview, a "Format help" cheatsheet, and a versions table with Unpublish actions.
• CLI:

  agnes admin news show                 # current published
  agnes admin news draft                # active draft (or none)
  agnes admin news edit \
      --intro '<p>Short HTML perex.</p>' \
      --content '<h1>Title</h1><p>Body.</p>'
  agnes admin news edit --from news.yaml      # YAML/JSON {intro, content}
  agnes admin news publish              # flip active draft → published
  agnes admin news unpublish 5          # roll back v5; web shows next-highest published
  agnes admin news versions
  agnes admin news export news.yaml     # round-trip to a file
  

Both surfaces sanitize on save through src/sanitize_news.py (Rust-backed nh3).

Allowed tags

p, br, hr,
h1, h2, h3, h4, h5, h6,
ul, ol, li,
strong, em, b, i, u, s,
code, pre, blockquote,
a, img,
span, div, section,
table, thead, tbody, tr, th, td,
details, summary,
figure, figcaption,
iframe                       (only with allowlisted src — see below)

Anything else (<script>, <style>, <object>, <embed>, <base>, <link>, <meta>, <form>, <input>, all event-handler attributes like onclick/onerror/onload) is stripped.

URL schemes

• <a href>, <img src>: http://, https://, mailto:, or relative paths (no scheme). javascript: and data: are blocked.
• <a target="_blank">: the sanitizer auto-injects rel="noopener noreferrer" so target-blank links can't pivot the parent window.
• <iframe src>: must start with one of the video-host prefixes. Any other src strips the entire iframe element:
  • https://www.youtube.com/embed/…, https://youtube.com/embed/…, https://www.youtube-nocookie.com/embed/…
  • https://player.vimeo.com/video/…
  • https://www.loom.com/embed/…, https://www.loom.com/share/…

Allowed attributes

Tag	Attributes
a	href, title, target, class (rel is auto-managed by the sanitizer; do not set it manually)
img	src, alt, width, height
iframe	src, title, width, height, allow, allowfullscreen, frameborder
span, div, section, p, h1–h6, table, td, th, blockquote	class

The class attribute is permitted only on the structural tags listed; it's used for the documented vocabulary below. Custom classes that aren't in the documented list will pass the sanitizer but won't render any styling — there's no CSS for them.

Documented class vocabulary

Use these classes via copy-and-edit. They render consistently on /home (perex) and /news (full body). The CSS lives in one place: app/web/static/style-custom.css under "News content vocabulary (shared)" — editing it there updates /home, /news, and the /admin/news preview pane together.

Hero block — landing-page-style highlight

Blue-gradient block with eyebrow line, title, and a one-line lead. Same vocabulary the /home install hero uses; surfaced as div.news-hero so news authors can recreate the look without reaching into /home-specific selectors. Use sparingly — at most one per news entity, usually at the top.

<section class="news-hero">
  <div class="eyebrow">Release · v0.40</div>
  <h2>News section is live</h2>
  <p class="lead">A reusable hero block for landing-page-style highlights — eyebrow + heading + one-line lead in the brand-blue gradient.</p>
</section>

Callouts — boxed notice with colored left border

<div class="callout">
  <strong>Note:</strong> A neutral callout.
</div>

<div class="callout callout-info">
  <strong>FYI:</strong> Informational, blue.
</div>

<div class="callout callout-warn">
  <strong>Heads up:</strong> Yellow — needs attention.
</div>

<div class="callout callout-success">
  <strong>Done:</strong> Green — successful release / completed.
</div>

<div class="callout callout-danger">
  <strong>Important:</strong> Red — breaking change / required action.
</div>

Video embed — 16:9 wrapper

Wrap the iframe so it scales fluidly on narrow viewports:

<div class="video-embed">
  <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"
          title="Walkthrough video"
          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
          allowfullscreen></iframe>
</div>

Replace the src with the YouTube / Vimeo / Loom embed URL — anything else gets the iframe stripped on save.

Sections — visual breaks between topics

<section class="news-section">
  <h2>Big release this week</h2>
  <p>Body of this section.</p>
</section>

Two- or three-column grid

<div class="news-grid-2">
  <div>
    <h3>Left column</h3>
    <p>…</p>
  </div>
  <div>
    <h3>Right column</h3>
    <p>…</p>
  </div>
</div>

news-grid-3 works the same with three children. Both collapse to a single column below 720px.

Call-to-action button

<a class="news-cta" href="/setup-advanced">Open advanced setup</a>

Example: a release note

<!-- intro (shown on /home) -->
<p><strong>Agnes 0.40 is live.</strong> Highlights: new <code>agnes admin news</code>
   command, marketplace plugin discovery, and a 3× faster <code>/catalog</code>.</p>

<!-- content (shown on /news) -->
<section class="news-section">
  <h2>What changed</h2>
  <ul>
    <li><strong>News editor.</strong> Admins can publish updates to <code>/home</code>
        + <code>/news</code> from the web UI or CLI. See
        <a href="/admin/news">/admin/news</a>.</li>
    <li><strong>Marketplace.</strong> The Plugin Store now surfaces newly-released
        community plugins on the homepage.</li>
    <li><strong>Catalog speed-ups.</strong> Schema lookups cache locally; first-page
        load drops from ~800ms to ~250ms.</li>
  </ul>
</section>

<div class="callout callout-warn">
  <strong>Action needed:</strong> If you're on a custom plugin that pinned to
  <code>0.39</code>, bump the pin to <code>0.40</code> after upgrading.
</div>

<section class="news-section">
  <h2>Walkthrough</h2>
  <div class="video-embed">
    <iframe src="https://www.loom.com/embed/example-loom-id"
            allowfullscreen></iframe>
  </div>
</section>

<a class="news-cta" href="/setup-advanced">Open advanced setup</a>

What gets stripped

If you find something missing from the published render, it almost certainly fell into one of these buckets:

• A non-allowlisted tag (<script>, <style>, <object>, <form>, etc.) → stripped.
• An event handler (onclick, onerror, onload, onmouseover, …) → stripped.
• A javascript: or data: URL on href/src → URL stripped (element kept, attribute removed).
• An iframe whose src is not on the YouTube / Vimeo / Loom allowlist → entire iframe element stripped.
• A class attribute on a tag that isn't in the structural list → class stripped.

When in doubt, paste the candidate HTML into the /admin/news preview pane — the sandboxed iframe shows exactly what users will see.