itworx-knowledge-hub-Public/docs/11-markdown-and-linking.md

Markdown and linking

Canonical content

The canonical human-authored body of a page is Markdown stored in PostgreSQL and included in immutable revisions. HTML is derived and disposable.

Full exports use Markdown plus a manifest/frontmatter representation. Database metadata remains authoritative during normal operation.

Supported syntax

Initial profile:

• CommonMark;
• headings;
• emphasis and strikethrough;
• ordered/unordered lists;
• task lists;
• block quotes;
• fenced code blocks with language;
• inline code;
• tables;
• links;
• safe images through attachment references;
• footnotes when the selected parser supports deterministic export;
• Mermaid fenced blocks.

Raw HTML is disabled by default.

Managed import regions

Imported and derived pages may store four exact control tokens in canonical Markdown:

<!-- managed-source:start -->
<!-- managed-source:end -->
<!-- user-notes:start -->
<!-- user-notes:end -->

These tokens remain in PostgreSQL and immutable revisions so synchronization can replace only the managed source region and preserve user notes byte-exact. The renderer removes only these four exact tokens from a transient render copy, replacing them with line boundaries before Markdown parsing. Stored Markdown is never normalized by rendering. Unknown comments, HTML, scripts and event handlers are not recognized as controls and remain subject to the normal raw-HTML-disabled and allowlist-sanitized pipeline.

Internal wiki links

Author syntax:

[[Target title]]
[[Target title|Visible label]]

The editor autocomplete may insert an invisible stable marker or structured editor metadata, but exported Markdown must remain human-readable.

At publish time, each link records:

• source page/revision;
• authored target text;
• optional display text;
• resolved stable target ID;
• resolution state;
• occurrence or source range where practical.

Resolution order:

1. explicit stable target marker;
2. exact title in the same collection/subtree;
3. exact title in the workspace;
4. unique normalized match;
5. unresolved or ambiguous.

The UI must ask the editor to resolve ambiguity before or after publishing; it must not silently choose an arbitrary page.

Slugs

• Derived from title for readability.
• Unique only where required by routing policy; stable page ID prevents identity loss.
• Old canonical URLs redirect using ID.
• Slugs contain no authorization meaning.
• Import preserves the legacy path separately as provenance.

Heading anchors

Heading IDs are deterministic within a rendered revision. Duplicate headings receive stable suffixes. Links to headings use page ID plus anchor.

A heading rename may break an authored anchor; the system should detect this as a link maintenance warning but need not maintain a permanent heading identity in v1.

Rendering safety

• Parse using a fixed configured extension set.
• Do not pass raw HTML through.
• Remove only the four documented import control tokens from render input; never expose them in reader views, snippets or revision previews.
• Sanitize generated HTML with an allowlist.
• Rewrite external links with safe rel attributes.
• Reject javascript:, data: and unsafe protocols except explicitly generated safe image data where controlled.
• Render Mermaid with strict security and sanitized labels.
• Never allow Mermaid directives to access network/filesystem.
• Syntax highlighting is client-side or server-side without executing code.
• Cap nesting, token count and rendered size to resist pathological input.

Attachments in Markdown

Use a stable application URI:

![Alt text](attachment:550e8400-e29b-41d4-a716-446655440000 "Caption")

The renderer resolves it through authorized metadata/content endpoints. Exports rewrite it to a deterministic relative file path and include the attachment.

Ordinary external image hotlinking is disabled by default for privacy. The editor may store an external hyperlink instead.

Draft and revision behavior

The draft stores raw Markdown and typed metadata. Preview never changes published relations or search.

Publish:

1. validates size and parser limits;
2. parses internal links and attachment references;
3. authorizes all referenced private resources;
4. creates current state and immutable revision;
5. updates derived relations/search;
6. writes audit/outbox;
7. returns the new ETag.

Export frontmatter

Export may include:

id: 550e8400-e29b-41d4-a716-446655440000
title: PostgreSQL back-up herstellen
documentType: runbook
status: active
tags:
  - PostgreSQL
  - Back-up
updatedAt: 2026-07-31T18:00:00Z

Importers must not trust privileged fields such as author IDs, permissions or executable paths from frontmatter.