Note validators

Quick start

1. Create a note validators/required_frontmatter.md. The rules go in a jsonnet code block:

Every article needs a title and a description, both strings.

```jsonnet
local required = ['title', 'description'];

[
  {level: 'error', msg: 'missing frontmatter field: ' + f}
  for f in required
  if !std.objectHas(meta, f)
] + [
  {level: 'error', msg: f + ' must be a string'}
  for f in required
  if std.objectHas(meta, f) && !std.isString(meta[f])
] + (
  if std.objectHas(meta, 'tags') && !std.isArray(meta.tags)
  then [{level: 'error', msg: 'tags must be a list'}]
  else []
)
```

2. Attach it to a note through the validate field:

---
title: Publishing a vault
validate: "[[required_frontmatter]]"
---

3. Sync the vault. If the note has no description, the sync output shows:

notes/article.md
  [CRITICAL] validate validators/required_frontmatter.md: missing frontmatter field: description

The note is still saved and published. The warning marks it until you fix it.

Where you see the result

• Sync CLI. Messages are listed under each note. When there is at least one error, the CLI exits with code 1, so a script or an AI agent knows it has to fix something. Messages come with a sync that pushes notes: when nothing changed, the CLI pushes nothing and shows nothing. See CLI sync.
• Admin panel. Dashboard → Note Warnings always lists every note with its messages.
• Locally, without a server. trip2g lint <folder> prints the same messages. It is stricter than sync: it exits with code 1 on an error and on a warning alike. Put it in CI to stop invalid notes before they reach the site. See Linting your vault.

Attaching validators

validate takes one validator or a list:

validate:
  - "[[required_frontmatter]]"
  - "[[seo]]"
  - validators/session_has_image.md

A validator can be named as a wikilink or as a path, with or without .md. Lookup works the same way as for wikilinks in the text; a #heading part is ignored. A note passes only when none of its validators returns an error.

---
type: frontmatter-patch
include: ["blog/**"]
---

Blog posts also follow the required-fields and SEO rules.

```jsonnet
local own = std.get(meta, 'validate', []);
local list = if std.isString(own) then [own] else own;
{ validate: list + ['[[required_frontmatter]]', '[[seo]]'] }
```

Writing a validator

Validators are written in Jsonnet; the syntax you need is on Jsonnet in trip2g. Each jsonnet block of a validator has access to:

Every element in nodes has a type, a line (its line in the file, frontmatter included) and a depth (how deeply it is nested):

The block returns a list of messages. An empty list means the note is fine:

[
  {level: 'error', msg: 'what is wrong', line: 12},
  {level: 'warning', msg: 'worth a look'},
]

• error marks the note as invalid: CRITICAL in the CLI, and the CLI exits with code 1.
• warning is advice: WARNING, and the sync CLI exit code stays 0. trip2g lint still fails on it.
• line is optional. When given, the message shows it.

A validator that is itself broken never passes silently. A typo in Jsonnet, a result that is not a list, an unknown level or a validator that can't be found all produce a CRITICAL message on the note.

A validator can have several jsonnet blocks. Each one runs, and their messages add up.

Examples

These validators are taken from a demo vault that the trip2g test suite runs on every build.

local required = ['title', 'description'];

[
  {level: 'error', msg: 'missing frontmatter field: ' + f}
  for f in required
  if !std.objectHas(meta, f)
] + [
  {level: 'error', msg: f + ' must be a string'}
  for f in required
  if std.objectHas(meta, f) && !std.isString(meta[f])
] + (
  if std.objectHas(meta, 'tags') && !std.isArray(meta.tags)
  then [{level: 'error', msg: 'tags must be a list'}]
  else []
)

local want = ['Intro', 'Steps', 'FAQ'];
local got = [n.text for n in nodes if n.type == 'heading' && n.level == 2];

if got == want then []
else [{
  level: 'error',
  msg: 'sections must be %s, got %s' % [
    std.join(' → ', want),
    std.join(' → ', got),
  ],
}]

local last(xs) = xs[std.length(xs) - 1];
local init(xs) = xs[:std.length(xs) - 1];

local sections = std.foldl(
  function(acc, n)
    if n.type == 'heading' && n.level == 2 then
      acc + [{title: n.text, line: n.line, images: 0}]
    else if n.type == 'image' && std.length(acc) > 0 then
      init(acc) + [last(acc) + {images: super.images + 1}]
    else acc,
  nodes,
  [],
);

[
  {level: 'error', line: s.line, msg: '"%s" has no image' % s.title}
  for s in sections
  if std.startsWith(s.title, 'Session') && s.images == 0
]

[
  {level: 'warning', line: n.line, msg: 'image %s has no alt text' % n.src}
  for n in nodes
  if n.type == 'image' && n.alt == ''
] + [
  {level: 'error', line: n.line, msg: 'code block without a language'}
  for n in nodes
  if n.type == 'code_block' && n.lang == ''
]

local re = std.native('regexMatch');
local desc = std.get(meta, 'description', '');
local date = std.toString(std.get(meta, 'date', ''));

(
  if std.length(desc) > 160
  then [{
    level: 'warning',
    msg: 'description is %d chars, keep it under 160' % std.length(desc),
  }]
  else []
) + (
  if !re('^\\d{4}-\\d{2}-\\d{2}$', date)
  then [{level: 'error', msg: 'date must be YYYY-MM-DD, got "%s"' % date}]
  else []
)

local re = std.native('regexMatch');
local parts = std.split(path, '/');
local file = parts[std.length(parts) - 1];
local name = std.substr(file, 0, std.length(file) - 3);
local chunks = std.split(name, ' – ');
local tools = [
  'Claude Code', 'Cursor', 'ChatGPT', 'Gemini', 'Windsurf', 'Manual',
];
local err(msg) = {level: 'error', msg: msg};
local warn(msg) = {level: 'warning', msg: msg};

local checkTool(tool) =
  if std.member(tools, tool) then []
  else if re('^[A-Z][A-Za-z0-9 .]*$', tool) then [
    warn('new tool "%s"? add it to the list in this validator' % tool),
  ] else [
    err('tool "%s" must be a name like %s' % [tool, std.join(', ', tools)]),
  ];

if std.length(chunks) != 3 then [
  err('name must be "{project} {type} title – YYYY-MM-DD – tool"'),
] else
  local head = chunks[0], date = chunks[1], tool = chunks[2];
  (
    if re('^\\{[a-z0-9]+\\} \\{[a-z]+\\} .+$', head) then []
    else [err('name must start with {project} {type} and a title')]
  ) + (
    if re('^\\d{4}-\\d{2}-\\d{2}$', date) then []
    else [err('date "%s" must be YYYY-MM-DD' % date)]
  ) + checkTool(tool) + (
    local fmDate = std.toString(std.get(meta, 'date', date));
    if fmDate == date then []
    else [err('frontmatter date %s differs from %s in the name'
              % [fmDate, date])]
  )

Beyond the basics

Validators cover rules about one note at a time, without a clock. For anything else, run your own checker outside trip2g:

• A change webhook sends every changed note to your service. The service can check anything: other notes, external systems, the current date. See Webhooks.
• A cron webhook runs the check on a schedule, for rules that depend on time, such as "re-check this note after its stale_after date".

trip2g has no API that adds a warning to a note. The service reports back by writing notes: in the webhook response (changes[]) or through the API token. Two ways that work today:

• A report note. The service writes a note such as reports/validation.md that lists the problems. It shows up on the site and in search like any other note.

• A field plus a validator. The service writes the problems into a frontmatter field of the checked note, for example external_errors: ["no backlinks"], and a small validator turns the field into messages:

  [
    {level: 'error', msg: e}
    for e in std.get(meta, 'external_errors', [])
  ]
  

  The messages then show in the sync output and the admin panel like any other. This edits the author's note on the server, so it no longer matches their local copy.

Plans

Rules over the whole vault are planned, but how to build them is not settled yet:

• every note has at least one link, in or out;
• every folder has an index note;
• the target of supersedes is marked deprecated;
• a stale_after date has passed.

They need a different kind of validator: one that sees all notes and the current date, and runs without the per-note cache. The discussion is in issue #436. Until then, a check of your own next to trip2g always works: a change or cron webhook sends notes to your service, as described above.

What else to check

• The contract with a template. A layout reads cover, description and a ## Summary section. The validator makes sure every note that uses the layout has them.
• Notes written by agents. An agent writes a note, runs sync, gets exit code 1 with a list of messages, and fixes the note. This loop catches what the model got wrong in a given run.
• Data in notes. Events, products, people: price is a number, status is one of draft, review, published, and the date is in ISO format. Lists, charts and the API then get clean data.
• SEO and accessibility. A single # heading, no skipped levels (## followed by ####), alt text on images, a description under 160 characters.
• House style. Banned words, link text like "click here", sentences that run too long. A paragraph's text is in the text field of paragraph elements. Text inside table cells is not in nodes.
• Course structure. Every lesson has a video and a ## Quiz section.
• Telegram posts. The text fits the limit, and there is no more than one image.

Limits

• A validator sees one note. It can't check that a slug is unique across the vault, or that some other note links here.
• Validators don't block sync. An invalid note is saved and published with a warning. To block it, run trip2g lint in CI before syncing.
• A validator note is published like any other note.
• Results are remembered between syncs. A note is checked again only when it changes, when one of its validators changes or starts pointing to another note, or when any frontmatter patch changes. A server start, saving a patch in the admin panel, or a sync that brings a patch note checks every note that has validate again. With seven validators on about 850 notes, that pass takes about 4 seconds.

How it works inside, and what it costs: note validators (dev).