# Links and media

Authored Markdown links/images are rendered as written; MarkStack does not rewrite .md source references into title-derived reader routes or validate every target. Keep public assets local when appropriate, check their bytes/audience and test links on the actual deployed path.

# Source and reader paths

• content/guides/page.md is writer source, not a reader URL.
• /guides/workstation-check is an example generated leaf route.
• /guides/ is an example section landing.
• static/images/check.png is input asset; /images/check.png is root-host reader asset.
• #check-installed-tools is a fragment that must exist on target.

Leaf engine map omits slash; host can resolve directory/index slash form. Copy actual route from generated reader and observe host redirects rather than guessing a source filename mapping. A stable frontmatter title can preserve basename-renamed route; a section title change moves descendants.

[Run the workstation check](/guides/workstation-check/)
![An example tool check meeting the documented Node requirement](/images/check.png)

These are illustrative Field Guide paths. They work only when your source/assets actually create them. Do not call an example a verified live destination. The title-based map, link and heading fragment need independent checks.

# Relative versus root-relative

Deep reader paths and host trailing-slash redirects affect relative references. A source sibling is not automatically a reader sibling when titles differ. Prefer deliberate root-relative routes at root deployments, with correct prefixes for subpath deployments.

A browser 200 can still be fallback HTML/login/soft 404. Read the intended destination content/type, not status alone. Missing fragment can leave page at top without a network error. Build success proves generation, not that link/fragment exists.

# Heading permalinks

Build heading IDs lower-case heading text and replace runs outside JavaScript \w with dash. This differs from page slug normalization. Punctuation, non-Latin text and repeated headings affect fragments; duplicates receive disambiguated IDs through the anchor plugin.

Copy built permalink for the exact heading. Check resulting target after changing heading text. A page route can stay stable while its anchored links break. H2-H4 search entries use built IDs, so stale deployed index can send readers to old fragments.

Do not invent custom {#id} support, universal transliteration or a route override from unsupported metadata. Inspect generated HTML/permalink when imported syntax differs. Frontmatter and Content structure explain identity consumers.

# Local image workflow

1. Choose actual screenshot/photo/diagram that teaches the task.
2. Inspect pixels and metadata for names, keys, addresses and private source.
3. Put approved bytes in selected static input, such as static/images/check.png.
4. Write useful alt text plus the conclusion/expected result in prose.
5. Build and open image in real reader at phone/desktop widths.
6. Verify response type, intended version and deployed path/cache.

The output omits static from public URL. Markdown editor does not upload image bytes. A reference can look correct while file is absent from build inputs or wrong deployment. Arrange media through source/operator workflow rather than repeatedly saving identical text.

Alt text describes useful information, not merely “screenshot”. Surrounding text should let a reader complete the task without deciphering tiny image text. Actual UI screenshots need fictional data or explicit privacy review; a caption saying “example” does not sanitize real account details.

# Subpath sites

For https://docs.example.com/, author /images/check.png.

For https://example.com/docs/, author /docs/images/check.png.

On a deep page under /docs/, verify the same intended prefix.

baseUrl adjusts template-owned links/assets, not arbitrary Markdown href/src. Site URL is a separate metadata/origin setting. Setting baseUrl alone does not fix root-relative authored paths, move host files or automatically generate per-deployment content.

For two output locations, plan separate reviewed references/build content or a carefully tested relative strategy. Root local preview is not evidence subpath deployment works. Check exact live deep URL, resource requests, search destinations and generated 404 Return Home behavior at intended host.

# Remote resources and privacy

Remote media can expose reader network information, fail offline, change without source review or require unavailable credentials. Local bundles do not make those dependencies local. Do not hotlink confidential media from your own signed-in session and expect other readers to have access.

Preview frame allows permitted image resources but blocks authored script execution. Final reader loading policy can differ. Test both contexts; publish based on finished reader and expected audience/network. Local source path is not a secret once copied into public output.

# Downloads and other assets

static/downloads/field-guide-checklist.pdf

This can become /downloads/field-guide-checklist.pdf on a root deployment. Use correct base prefix where needed. Link with ordinary Markdown; no built-in attachment authorization, download audit or document sanitization is supplied.

Never place users files, hashes, credentials, private source backups or temporary confidential exports in static. Dotted static files are not protected by Markdown scanner exclusions. Deleting a page can leave its assets hosted. Remove/rebuild/deploy deliberately and test old URLs; security incident response may need more than deleting one link.

# Links across reorganizations

Before renaming title/folder, inventory authored links, external inbound links you control, fragment targets and attachment paths. Preserve old source/output and writer drafts. Supported section rename handles assignments/session effects but not all host redirects/browser profiles.

After build, inspect changed route map and fix source links. Configure/test redirects through host’s supported method; MarkStack has no automatic redirect migration. Verify old URL status/destination and ensure no obsolete files survive add-only deployment.

# Release gate

A successful build is one step, not this whole gate. Review and release and Validation limits define generated versus host evidence.