Posts / Agent guide: how to write a post
Post

Agent guide: how to write a post

How to write a post on this site

This file is for an AI assistant. It is not a post: it is draft: true, so it only shows up in a draft build (scripts/preview.sh), never on the published site.

In this source the shortcodes are escaped as {{< name >}} so that Hugo does not run the examples. In a real post, write them without the /* and */ (see the reference post).

Reference post: liguria-trains-data-study.md. Read it before writing. When in doubt, imitate it. For a short technical explainer (no data), the second reference is ros2-daemon.md.

1. Files and front matter

  • One post = one file content/posts/<slug>.md, slug in lowercase kebab-case.
  • Images go in static/images/<slug>/ and are used as /images/<slug>/name.png.
  • Front matter (copy the one of the reference post):
---
title: "Specific title, with the key numbers if it is a data study"
date: YYYY-MM-DD
description: "One or two sentences: what the post answers and what the reader gets."
tags: ["statistics", "modelling"]   # lowercase, reuse existing tags before creating one
topic: "Data"                       # decides the group on the Posts page, see below
series: ""                          # same value on every part of a multi-part post
image: "images/<slug>/thumbnail.png"
pinned: false                       # true: shown in the "Pinned" section at the top of the Posts page
draft: true                         # false only when the post is ready
changelog:                          # optional, see "Changelog" below
  - date: YYYY-MM-DD
    note: "What changed, in one line."
---
  • topic must be one of the groups in $order of layouts/posts/list.html (today: ROS 2, Real-time, Data, Linux and tools, About). Any other value lands in a “More” group: add the new topic to $order instead.
  • No aliases on a new post (they exist only for the old /blog/ URLs).
  • Start with draft: true, so nothing leaves before the user has read it.
  • Changelog. Once a post is published (draft: false), every change that a reader could notice adds one entry to changelog: today’s date and one line that says what changed (“Added the xacro example”, “Fixed the default of the publication mode”). Typos and wording do not need an entry. A post that has never been published has no changelog: its first version is the post itself. The entries are Markdown (inline code and bold are fine). The site shows a “Changelog” button under the title, which opens the list (newest first), and the “Updated” date of the post is the newest entry. Do not add entries for changes the user has not asked to publish.

2. Structure

  1. Why this post exists (first H2, no more than three short paragraphs): the situation or the question, where it comes from, what this post does and does not do (“step two: study the data before modelling it. Not to prove anything, but to know what I am working with”).
  2. The key numbers or the takeaway, for readers who keep only one section: a {{< stats >}} block of 6 to 8 cards in a data study, or a {{< callout title="Key takeaway" >}} in an explainer.
  3. The material the rest depends on (data, tables, definitions, setup): what it is, its size, its flaws, how it was filtered. State the choices that shape every result before the results.
  4. The body: H2 for a theme, H3 for a question inside it. Each section answers one question and ends on a finding, not on a transition.
  5. Limits (optional, a short list of what the study cannot say). An explainer can state its caveats where they apply instead.
  6. Quick remember (## Quick remember, the last H2 before ## References): what the reader should keep if they scroll straight to the end. It repeats the conclusions of the body, it never adds a fact. See the rules below.

Quick remember rules.

  • 4 to 6 bullets, one or two sentences each, the key idea in bold at the start of the bullet.
  • Same order as the body, so that the section reads as its summary.
  • In a comparison, say what the differences are (“the differences are three: A, B and C”) and which former differences have disappeared, instead of repeating the whole comparison table.
  • Keep the actionable rule (what to choose, what to run first, which message points to which cause).
  • Same numbers, names and commands as the body, word for word. A number that appears here must appear in the text above. No new fact, no new reference, no first-person remark.
  • Plain Markdown: the heading must be exactly ## Quick remember, followed directly by a bullet list. static/css/post-components.css turns that list into the navy card with a yellow check per point, so do not wrap it in a callout or a shortcode.

Never leave a section with only figures: every figure is followed by the text that says what to see in it.

3. Voice and content rules

  • First person, plain English, short sentences. Say what was done and why.
  • Concrete over general: a named station, a named train, a date, a unit. A claim without its number is rewritten or removed.
  • Bold the finding of a paragraph, once. Italic for a quoted phrase or a term being defined. No hype, no filler (“it is interesting to note”).
  • Data says what and when, not why. Mark any interpretation as such (“an interpretation, the data only shows the effect”). Do not invent a cause.
  • Be honest about the data: coverage, missing values, what was filtered out and how many rows it removed, what is small-sample (“rests on small numbers”). A negative result is reported (“one hypothesis does not hold”).
  • Numbers: thousands with a comma (22,641), a space before % (30 %), units always (minutes, km), the same number identical everywhere it appears (summary, body, caption). Round to what the data supports.
  • Every acronym, column name and symbol is defined where it first appears.
  • Do not publish what was not checked. A result still to confirm goes in an HTML comment <!-- ... --> (as the permutation tests in the reference post), not in the text.

4. Maths

  • Display equation: the equation shortcode, then a bullet list defining every symbol (name, meaning, unit or range), then a sentence that gives the value found.
{{< equation >}}
d = t_{\text{real}} - t_{\text{sched}}
{{< /equation >}}

- $t_{\text{real}}$ and $t_{\text{sched}}$ are the real and the scheduled arrival;
- $d$ is the delay in minutes, negative when the train is early.
  • Inline maths with $...$. Introduce an equation only when it removes an ambiguity (a threshold, a rate, a conditional probability), never to decorate.
  • State the rule used to select or filter data as an equation or a short rule with its numbers (see “Which days” in the reference).

5. Figures, tables, code

  • Figure: {{< figure src="/images/<slug>/x.png" caption="..." width="700" label="x" >}}.
    • One message per figure. Width 600 to 700, 900 for maps.
    • The caption tells how to read it and gives the number to retain (“Reading the curve: the point at k = 5 says that…”).
    • Say in the caption what the colours and sizes mean. Same colours for the same idea across figures (weekdays blue, weekend orange in the reference).
    • Credit data sources when required (OpenStreetMap: © OpenStreetMap contributors (ODbL)).
    • Refer to a figure in the text with {{< figref x >}} when useful.
  • Table: Markdown, field names in backticks, a short sentence before it saying what one row is, and one after it saying what to notice.
  • Code or data schema: fenced block with the language (sql, bash, text), comments on the fields, real values from a real example.
  • Diagram of a mechanism: {{< mermaid caption="..." label="name" >}} (see ros2-daemon.md). A diagram is a figure like an image: it is numbered with the same counter (“Fig. 1 - caption”), so a post with a mermaid, an image and another mermaid has Fig. 1, Fig. 2 and Fig. 3.
  • Citing a figure or a diagram. Give it a label="name" (lowercase, no spaces), then write {{< figref name >}} in the text: it becomes a link “Fig. N”, whatever the kind of figure, and it works before the figure as well as after it. Prefer it to “the figure below”, which breaks when a figure is moved. A caption written for a diagram may contain <code>.
  • Stat cards: {{< stats >}} containing {{< stat value="..." label="..." >}}text{{< /stat >}}. Value short and striking, label says what it counts, the text gives the context and points to the section that explains it.
  • Timeline or steps: {{< timeline >}} containing one {{< event date="2004" title="DDS 1.0" tag="standard" >}}text{{< /event >}} per item. Use it when the content is an ordered sequence: a history with dates (see cyclonedds-vs-fastdds.md), or the steps of a process, with date="Step 1" or a state name (see ros2-daemon.md and ethercat-state-machine.md).
    • tag colours the card and adds a chip: standard, cyclone, fastdds, ros2 (the four colours of the DDS post, with an automatic legend), step (neutral, no chip) or key (yellow chip “Key step”, for the one step the rest depends on).
    • {{< timeline legend="false" >}} hides the legend: always do it for step and key.
    • The text of an event is Markdown (code, bold, citations). Keep it to two or three sentences, and do not use a timeline when a diagram already shows the same sequence (mermaid).

6. References

Every post that states a fact from outside (a standard, a date, a version, a default, a number) ends with a ## References {#references} section. The word is References, not “Sources”.

  • Cite in the text with [[n]](#references) right after the claim it supports, where n is the number of the reference. Several references for one claim: [[3]](#references), [[4]](#references). Put the number in a table cell when the cell is the claim.
  • One reference is one link. The whole line is the link, so a reference never has two links. If an item needs two pages, make two references. Never list something as a reference without a link: “from my notes” or “read in the source code” is not a reference. Link the file or the page.
  • Write them with the shortcodes, which add the number, the domain of the site and the new-tab behaviour:
{{< references >}}
{{< ref "https://docs.ros.org/en/jazzy/Concepts/Basic/About-Command-Line-Tools.html" >}}ROS 2 documentation, About Command Line Tools (Jazzy): the CLI starts a daemon in the background.{{< /ref >}}
{{< ref "https://man7.org/linux/man-pages/man7/pty.7.html" >}}Linux man-pages, `pty(7)`: pseudoterminal master and slave.{{< /ref >}}
{{< /references >}}
  • The text of a ref is: publisher, title: what the page establishes (one sentence, so the reader knows why it is there). Code spans are allowed. Do not add the domain, the shortcode does.
  • Only cite what was checked. Open or search the page, and cite the page that says the thing. A forum post is a reference for “people report this”, not for “the documentation says this”. When references disagree, say so in the text instead of picking one.
  • ROS 2 sources only, when there is a choice. Cite docs.ros.org (a distribution that is named in the post), control.ros.org, the MoveIt 2 documentation or the repository of the package, never the ROS 1 wiki (wiki.ros.org), even when the ROS 1 page is the more detailed one. If only the ROS 1 page says it, look for the ROS 2 tutorial or the source of the package; if there is none, reword the claim to what the ROS 2 pages state, or remove it.
  • Number the references in order of the list, then renumber the citations if you insert or split one. A short paragraph above the list is fine (“the figures come from my own collector”), but it is not a reference and never carries a number.
  • No first-person process remarks in the post (“I did not find…”, “could not be opened from my environment”). Either the claim has a reference, or it is not in the post. Tell the user about the gaps in your reply instead.
  • Do not use an arrow or any special glyph for external links: the site font does not have it and shows a “?”.

Where the components live, if one has to change: the shortcodes references, ref, timeline, event are in layouts/shortcodes/, and their style (with the style of links and of the [n] citations) is in static/css/post-components.css, shared by all posts. Change it there, never inside one post.

7. Before saying it is done

  • Front matter complete, topic known, tags reused, draft as agreed.
  • The first section says why, and the post can be read from its key numbers alone.
  • A ## Quick remember section ends the post, before ## References, and every point in it is already in the body.
  • Every number in the summary matches the body and the captions.
  • A published post that changed has a new changelog entry; a draft has none.
  • Every symbol and acronym is defined; every figure has a caption that teaches.
  • Interpretation is marked as such; a Limits section exists.
  • Every outside fact is followed by a [[n]](#references), every reference is one link, and the list uses {{< references >}} and {{< ref >}}.
  • A sequence of dated events or of steps is a {{< timeline >}}, not a bullet list, unless a diagram already shows it.
  • hugo builds without error; preview with scripts/preview.sh and look at the page (figures, equations, filters on the Posts page).
  • Nothing committed or pushed without the user asking.