Readpage Authoring & Styling Guide

How to write rich documentation for the readpage reader — callout boxes (like the red security warning), image galleries, diagrams, and more. Each section shows a live example followed by the source to copy.

Why this works: readpage builds the docs with Hugo, and its markup is configured with unsafe = true (hugo.toml). That means raw HTML inside Markdown is rendered, which is what lets you style content (coloured boxes, etc.) beyond plain Markdown.

Callout / alert boxes

The coloured boxes are just a small raw-HTML <div> with an inline style. Copy one of the variants below and edit the text.

Live examples

Source

<div style="border-left:4px solid #c0392b;background:rgba(192,57,43,0.08);padding:12px 16px;border-radius:6px;margin:14px 0">
<strong style="color:#c0392b">⚠️ DANGER — something is unsafe.</strong>
<p style="color:#c0392b;margin:8px 0 0">Body text. Use for security risks or data loss.</p>
</div>

Colour palette (works on both light and dark themes):

Tip: keep the box body as plain HTML (<p>…</p>). Goldmark does not process Markdown inside a raw-HTML block, so **bold** won’t work there — use <strong> / <em> instead.

For a lighter touch, plain Markdown blockquotes also render and need no HTML:

Note: a normal Markdown blockquote — good for low-emphasis asides.

Image galleries

readpage ships a custom gallery shortcode for a responsive image grid (no page bundle needed — works for flat, named files).

Live example

Source

{{< gallery "screenshots/product/website-platform-1.png" "screenshots/product/website-platform-2.png" >}}

• Each argument is an image path. Bare paths resolve under /assets/ (e.g. screenshots/x.png → /assets/screenshots/x.png); absolute (/…) and http(s) paths pass through unchanged.
• Images live in the repo’s assets/ folder (readpage mounts it at /assets/).
• Naming: when several pages share one folder, prefix files per page (website-platform-1.png, …) so they don’t collide.

Single images

Plain Markdown works for one-off images (this is how most service docs embed screenshots):

![Alt text](../../assets/screenshots/category/name-DD.MM.YYYY.png)

The path is relative to the current file. From a top-level section like product/, use ../assets/...; from docs/services/CATEGORY/ (e.g. docs/services/media/), use ../../../assets/....

Diagrams (Mermaid)

Mermaid renders in readpage — good for architecture and flow diagrams without image files.

Live example

flowchart LR
  A["Author"] --> B["Git push"] --> C["readpage build"] --> D["Live docs"]

Source

```mermaid
flowchart LR
  A["Author"] --> B["Git push"] --> C["readpage build"] --> D["Live docs"]
```

Standard Markdown

The usual Markdown all renders: headings, tables, fenced code blocks (with syntax highlighting), task lists, links, and a table of contents (enabled via showTableOfContents: true in front-matter).

---
title: "My Page"
description: "One-line summary used in listings and search."
showTableOfContents: true
---

Where files live

Worked example

A callout used the way you would on a real page — here filled with placeholder text so you can see how a longer body reads inside the box:

<div style="border-left:4px solid #2f80c2;background:rgba(47,128,194,0.08);padding:12px 16px;border-radius:6px;margin:14px 0">
<strong style="color:#2f80c2">ℹ️ Example note</strong>
<p style="color:#2f80c2;margin:8px 0 0">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</div>