Improving Ordinal

This page collects known issues in Ordinal and outlines possible directions for improvement.

Bold and italics parsing relies on simple regular expressions. Certain edge cases break, especially around punctuation, underscores, and code-like text.
The parser handles frontmatter, Markdown transformation, TOC collection, and backlink recording in a single pass. Ordering matters, and small changes can break unrelated behavior.

External links open in new tabs but do not currently add rel="noopener noreferrer".

There are no incremental builds. Every run walks and renders everything in scope.
Template validation is minimal. Missing templates log errors and produce empty output instead of failing fast.
Sass is a hard runtime dependency.

A category only exists if a folder contains a matching section file. You cannot define a category independently.
Section files are regenerated on every run, even when their content has not changed.
Orphan cleanup matches files by stem only. If two categories contain entries with the same stem, the wrong HTML file can be deleted.
Media files are copied on every build. There is no checksum or timestamp comparison to skip unchanged files.

Slug handling is inconsistent. Some paths include category prefixes, others do not.
Several context fields exist primarily to satisfy current templates. Template changes can quietly break context assumptions.
Most failures log and fall back to defaults. This keeps the site building but makes data issues easy to miss.
last_modified conflates two meanings: rebuild time and content change time. Rebuild time currently overwrites author intent.

get_articles_list() scans the filesystem on every call, rereading the same files repeatedly.
Only content/articles participates in taxonomy. Other categories are excluded unless logic is duplicated.
There is no shared cache between listing passes.

The fingerprint ignores changes to domain, tags, division
Renames preserve GUID identity but do not record rename events.
--commit-all writes many rows one by one. SQLite handles it, but the write pattern is inefficient.
Schema migration is additive only. There is no mechanism for altering existing tables. this should be a priority.

Snapshots only store files. There is no metadata describing what changed or why.
Every snapshot copies all HTML files, even when nothing changed.
Restoring a snapshot overwrites public/ directly. The previous output is not preserved. Which is very ironic.

General Directions

Seed once from frontmatter, then treat the database as the source of truth. (In Progress)
Extend revision database to help with file change detection to avoid unnecessary work.
Make failure modes obvious where correctness matters.

markdown_parser.py mixes frontmatter parsing, markdown transforms, TOC building, and backlink tracking.

This could become:

frontmatter.py,

markdown_render.py,

toc_builder.py,

backlinks.py,

html_renderer.py handles template rendering, static copying, build orchestration, and commit flows.

This could become:

render_pipeline.py,

static_assets.py,

build_index.py,

commit_flow.py (already separate, but still heavily tied in)

The goal should be to make each module have one responsibility so future changes don't break unrelated behavior