Subreddit Notes Schema¶

Subreddit notes are moderator-written wiki pages attached to a shared index. They are distinct from usernotes (per-user annotations): subreddit notes are general-purpose text documents — rule summaries, ban templates, workflow guides — that the whole mod team can browse and search from within Toolbox. This feature was called “personal notes” in classic Toolbox 6.x.

Overview¶

Layout	Wiki pages	Used by
NXG (v2)	`toolbox-nxg/notes` (index), `toolbox-nxg/notes/<slug>`, …	Toolbox-NXG
Legacy (v1)	`notes/index` (notes array only), `notes/<slug>`, …	Older Toolbox builds; NXG compat mirror

NXG reads and writes the toolbox-nxg/notes index and toolbox-nxg/notes/<slug> pages. When 6.x compatibility is on, every write is mirrored to the legacy notes/index and notes/<slug> pages; subreddits that could not be moved onto the NXG layout use the legacy pages only. When the index page is missing or malformed, NXG scans existing wiki pages for the note page prefix and builds a bootstrap index from any pages it finds.

Index page (`toolbox-nxg/notes`, legacy `notes/index`)¶

The index is a JSON object that lists every note and caches aggregate metadata. NXG writes schema v2; the legacy mirror is a v1 subset with the aggregate fields stripped.

NXG index (v2)¶

{
    "version": 2,
    "notes": [
        {
            "slug": "ban-template",
            "title": "Ban Template",
            "createdAt": 1700000000000,
            "updatedAt": 1701000000000,
            "archived": false,
            "tags": ["bans", "templates"],
            "author": "moderatorname"
        }
    ],
    "tags": ["bans", "templates"],
    "authors": ["moderatorname"]
}

Field	Type	Description
`version`	`2`	Schema version
`notes`	`SubredditNoteMeta[]`	Ordered list of note metadata records
`tags`	`string[]`	Sorted unique list of all tags across all notes; recomputed on every save
`authors`	`string[]`	Sorted unique list of all authors across all notes; recomputed on every save

Legacy index (v1)¶

{
    "version": 1,
    "notes": [ ... ]
}

The legacy index has only version and notes; the tags and authors aggregate fields are absent. version is always 1 on the legacy mirror. NXG up-converts a v1 index by recomputing the aggregates.

`SubredditNoteMeta`¶

Each entry in the notes array is a metadata record for one note. The note’s body content is not stored in the index — it lives in the note’s own wiki page (toolbox-nxg/notes/<slug>, mirrored to notes/<slug>).

Field	Required	Type	Description
`slug`	yes	string	URL-safe identifier; used as the wiki page name suffix (`toolbox-nxg/notes/<slug>`). Never `"index"`.
`title`	yes	string	Human-readable display title. Derived from the slug (`"my-note"` → `"My Note"`) if absent.
`createdAt`	yes	integer	Creation timestamp in epoch milliseconds
`updatedAt`	yes	integer	Last-updated timestamp in epoch milliseconds
`archived`	yes	boolean	When `true`, the note is hidden from the default list but retained
`tags`	yes	`string[]`	Free-form tag strings; empty array when none
`author`	no	string	Reddit username of the mod who created the note; absent on notes migrated from older formats

Slugs are trimmed and deduplicated on read: if the same slug appears twice in the raw notes array, only the first occurrence is kept. The slug "index" is rejected and never stored. Other fields are coerced on read: a missing createdAt/updatedAt becomes the current time, archived is true only when literally true, and non-string or blank tags are dropped.

Note content pages (`toolbox-nxg/notes/<slug>`)¶

Each note’s body is stored as a plain wiki page at toolbox-nxg/notes/<slug> (legacy: notes/<slug>). The content is plain Reddit Markdown with no JSON envelope — you read and write it directly as the wiki page content.

There is no content schema version. The index is the authoritative list of which slugs exist; a note page without a matching index entry is ignored by Toolbox but is otherwise harmless.

Reading notes¶

To enumerate all notes:

Fetch and parse toolbox-nxg/notes (or notes/index on a subreddit still on the legacy layout). If the page is missing or not valid JSON, treat the subreddit as having no notes.
Normalize: if version is 1, the tags and authors aggregates are absent — compute them from the notes array yourself if you need them.
For each entry in notes, the note body is at toolbox-nxg/notes/<slug> (legacy: notes/<slug>) as plain wiki content.

Writing notes¶

To create or update a note:

Read and normalize the current toolbox-nxg/notes index.
Write the note body to toolbox-nxg/notes/<slug> as plain wiki content.
Add or update the SubredditNoteMeta entry for <slug> in the index’s notes array.
Recompute tags and authors from the updated notes array (sort and deduplicate).
Write the updated index back to toolbox-nxg/notes as JSON. If 6.x compatibility is on, also write the body to notes/<slug> and the v1 index (version and notes only) to notes/index.

To archive a note without deleting it, set archived: true in the index entry and leave the content page untouched.

To delete a note permanently, remove it from the index’s notes array. Its wiki page stays behind, since Reddit’s wiki API cannot delete pages. NXG lists notes from the index, so it ignores the orphaned page - unless the index page itself goes missing, in which case NXG rebuilds the index from the subreddit’s wiki page list and the page reappears as a note. NXG never propagates deletions from the legacy mirror into the NXG index (a missing legacy entry is indistinguishable from a failed mirror write), so deletions performed via the legacy notes/index will not remove entries from the NXG index.

Reconciliation with the legacy index¶

When both a NXG (v2) index and a legacy (v1) index exist and 6.x compatibility is on (and again whenever the layout migration re-runs), NXG merges them by slug union:

Slugs only in the legacy index were created by an older Toolbox build and are appended to the NXG index.
Slugs only in the NXG index are kept unchanged; a deletion in the legacy index is assumed to be a mirror write failure, not a real delete.
Slugs present in both keep the NXG entry (it carries richer v2 metadata).

The aggregates (tags, authors) are recomputed whenever the merge adds entries.