Markdown-first authoring
If Goldmark can preserve the intended meaning, prefer a native Markdown form. Keep a shortcode only when the native form cannot provide its capability. For a new content scenario, extend an existing shell and data model. Do not create a parallel rendering system.
Context
OINK supports short manuals, large references, release archives, landing pages, and books. A survey of eleven consumer sites examined more than five thousand Markdown files and found both extremes: pages with almost no theme syntax and pages assembled from many nested shortcodes and local layout overrides.
A component API optimized only for the second group becomes a private DSL, while one limited to plain Markdown leaves books, rich figures, tab groups, and structured releases to site-local HTML. The useful boundary is capability, not novelty.
Decision
OINK applies the following order:
- Native Markdown first. Lists become Steps, Cards, or FileTree markers; tables become Fields or matrices; blockquotes become callouts; fenced code, images, and passthrough blocks carry attributes through render hooks.
- Shortcodes for missing capability. A full-form shortcode remains where CommonMark indentation, nested containers, processing options, or cross-page registration cannot express the same result safely.
- One semantic implementation. Native and full forms share normalization, partials, and an output contract, making them one component rather than two components with the same appearance.
- One extension line. A new Landing section joins the section registry; a new Blog presentation remains a Blog variant; Book numbering joins the content primitive and navigation systems. OINK does not add a second card, landing, navigation, or article shell for one feature.
- Facts stay outside presentation strings. Versions, repositories, dates, and ordered records come from front matter, site parameters, or data files. A shortcode argument is not a second source of truth.
Output contract
An authoring form is complete only when it defines a result for its semantic content in every enabled output:
| Output | Requirement |
|---|---|
| HTML | Semantic server-rendered content; JavaScript only enhances it |
| Static, expanded, and free of controls that require interaction | |
| Markdown / LLMS | Source-shaped prose, links, lists, tables, and fences; no component HTML |
| RSS | Safe static content or an explicit omission |
This requirement prevents an HTML-only component from removing or corrupting content in agent output, feeds, or a printable book.
Trust and presentation
Render hooks and shortcodes use explicit allowlists to remove unsafe URL schemes, inline event handlers, and arbitrary style input. Author-provided classes are accepted only where the documented contract permits downstream site CSS. Icons use one Font Awesome class pair, without a second icon-ID language.
Consequences
- A proposed component must first show why Markdown plus an existing hook is insufficient.
- Keeping a full-form shortcode requires a named capability and tests for both forms reaching the same normalized output.
- Shell variants use independent presentation keys so opting into a hero or a flow outline does not change taxonomies, feeds, pager order, or content type.
- Consumer evidence is dated research, not a permanent excuse to freeze an accidental syntax. The current public surface remains defined by the component contract and shell contract.
Verification
Theme component, Book, output, and golden checkers test the authoring contract, followed by this site’s bilingual examples and browser suites for the integrated result. The Goldmark behavior that supports native forms is recorded in block-attribute research.