SEMANTIC DOCUMENTS · V1

Rich documents.
Still just Markdown.

Skald adds meaning between ordinary Markdown blocks, then lets CSS decide how that meaning should look. The file stays yours. The document gets smarter.

Markdown →source
Document tree →model
CSS →presentation
HTML / DOMrenderer
01 · Meaning, not layout

The source says what it is. The theme decides what it looks like.

A semantic container groups real Markdown blocks without turning them into one proprietary widget. Headings stay headings. Tasks stay tasks. Images stay images.

project-brief.md
:::aside

## Historical context

This decision came from the first
local-only prototype.

- Sync did not exist yet
- The server came later
- The constraint may now be obsolete

:::
Rendered by Skaldaside

Historical context

This decision came from the first local-only prototype.

  • Sync did not exist yet
  • The server came later
  • The constraint may now be obsolete
Aside:::aside

Supporting context, caveats, definitions and background that should not dominate the main flow.

Gallery:::gallery

Images or media that belong together semantically, regardless of whether the theme uses a grid, strip or essay layout.

Group:::group

A deliberately generic grouping primitive for related blocks while real usage reveals future semantic types.

03 · Same semantics, different CSS

The document does not encode its costume.

This is the part that makes the model worth having. The Markdown and semantic type stay identical while the visual language can change radically. Human beings apparently enjoy both consistency and infinite customization. Skald can indulge both.

PREVIEW THEME
:::aside

## Observation

The northern sample contains a
second mineral band worth logging.

:::

Observation

The northern sample contains a second mineral band worth logging.

Public theme contract: .sk-container, .sk-container__content, .sk-container--aside, .sk-container--gallery, and .sk-container--group. Themes style semantics. They do not have to reverse-engineer arbitrary markup.
04 · Editor workflow

The fences are a file format detail, not the everyday UX.

Use Cmd/Ctrl+I and choose Aside, Gallery or Group. With a selection, Skald wraps the selected Markdown instead of converting it.

Selected blocksbefore
## Context

- First point
- Second point
Cmd/Ctrl+I → Asideafter
:::aside

## Context

- First point
- Second point

:::
Inside the container, those blocks remain independently editable. The heading does not become “aside-heading markup”; it remains a heading with a semantic parent.
05 · Runtime model

A tree in memory. A text file on disk.

The canonical note never becomes an opaque rich-text document. Skald parses it into a source-aware runtime tree, renders from that tree, and keeps source coordinates for editor operations.

Markdown sourceproject.md

:::aside
## Context
Paragraph
:::
→
Document tree
  • Document
  • Container · aside
  • ↳ Heading
  • ↳ Paragraph
→
DOM + themesection.sk-container--aside
h2.sk-h2
p.sk-p
Live editor compatibility: the editor currently consumes a flattened projection of the tree. Child blocks retain source line ranges and container metadata, so the runtime can become tree-shaped without throwing away the source-oriented caret and task behavior that already works.
06 · Vocabulary rules

Semantics age better than fashionable layouts.

A permanent container name should still communicate something useful when every stylesheet is deleted. That is the filter for future additions.

Good semantic namesaside · gallery · comparison · sources

They tell Skald what the content means. Different themes can present them differently.

Bad layout namesgrid-3 · two-column · left-sidebar · wide-card

They fossilize one rendering decision into the note format and make tomorrow's theme fight yesterday's syntax.

V1 constraint: containers cannot contain containers. That is deliberate, not parser laziness wearing a tie. Most useful compositions work with one semantic level, and editing stays much simpler while the model proves itself.
07 · Portability

Richer in Skald. Still recoverable without it.

A generic Markdown viewer may show the ::: markers instead of the intended composition. The prose, headings, lists, tasks, images and links between them remain readable Markdown.

The portability promise

A Skald note should remain understandable and recoverable outside Skald, even when its richer presentation is lost.