Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/11-markdown-and-linking.md

@@ -0,0 +1,157 @@
+# 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:
+
+```text
+<!-- 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:
+
+```text
+[[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:
+
+```text
+![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:
+
+```yaml
+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.