# Content structure

MarkStack builds a selected Markdown tree into title-derived reader routes. Physical files are writer/storage identity; titles are reader identity. Organize by reader tasks and use landings for learning order rather than relying on alphabetical sidebar alone.

# Minimal useful tree

content/
  _index.md
  guides/
    _index.md
    workstation.md
    first-build.md
    advanced/
      _index.md
      tuning.md
  operations/
    _index.md
    reader-check.md

Home states purpose/audience and links into useful groups. Guides landing explains first tasks; Operations landing explains ongoing checks. A nested Advanced folder is a reader grouping inside the guides writer assignment, not a new independently assignable top-level section.

Normal scans process lowercase .md suffix and skip dot-prefixed entries. A dotted source exclusion is not a secure confidential storage policy. The entire static input is copied under its own rules, including bytes no page links to. Keep accounts/private source outside publishable inputs.

# Physical path versus route

• guides/_index.md titled Guides plans /guides/.
• guides/workstation.md titled Workstation check plans /guides/workstation-check.
• Same file titled Developer setup plans /guides/developer-setup.
• Folder title Getting started changes descendant prefix to /getting-started/.
• Explicit unchanged title can preserve route after basename rename.

Leaf map paths omit trailing slash; output uses <route>/index.html. Hosts/preview can redirect to directory-slash URLs. Distinguish engine map/index value from resolved HTTP URL rather than promising one universal canonical host behavior.

Fallback title replaces filename/folder dashes/underscores with spaces and capitalizes word starts. Page title slug lowercases, removes everything except ASCII lowercase letters/digits/whitespace/dash, turns whitespace to dash, collapses repeated dash and trims edge dash. It is not transliteration or Unicode-friendly routing.

For title: Setup: Linux, punctuation removal produces setup-linux. A non-Latin-only title can collapse to empty slug/root-like route and collide. Choose a valid stable ASCII route-bearing title at this pin; do not present multilingual/RTL support as already solved. Heading anchors use a different normalization function.

# Folder and article order

A deliberate learning sequence belongs in numbered landing links. Readers can still browse alphabetically, but should not infer prerequisites from title order. Avoid artificial filename numbers when explicit title controls routes and sorting anyway.

Nested folder ordering uses its own _index.md, like top level. Deep nesting makes phone context harder; prefer clear sections within a substantial page when tasks do not need separate routes.

# Landings and absent _index.md

Folder map/navigation can exist without an index, using folder-name fallback, but normal processing only generates existing Markdown files. A sidebar folder link without a landing can therefore point to a missing page. Add a complete _index.md for each navigable folder and test its route.

Root _index.md is processed during normal scan and special homepage generation overwrites final root output. Final homepage title is Home with optional configured hero and custom body. Do not assume ordinary article metadata/previous-next furniture appears identically on homepage. Frontmatter explains field consumers.

# Hidden is navigation only

Strict boolean true is checked for section sidebar exclusion. String values are not the same. Previous/next follows flattened visible sidebar, so hidden pages/branches can lose sequence cards while remaining directly reachable/searchable. Search is not a privacy filter.

Use reader-host authentication for internal material and test all HTML/search/media paths. Editor section grants govern writing, not public reading. Security and privacy owns that separate perimeter.

# Collision validation

The URL map claims normalized full page/folder paths and treats trailing-slash variants as the same key. Two sources producing the same full path fail build and name both relative source paths. Same leaf title under distinct noncolliding parents can be valid.

A conflict can occur between article and folder, between punctuation variants or between titles collapsing to empty. Change source title/tree and update references. Do not patch generated filename to conceal it or rely on scan order to choose a winner.

No automatic source-link rewrite or redirect migration is provided. Successful generation does not validate all authored targets/anchors/images. Release review must check them. Admin catalog’s planned route is source preview, not proof build succeeded or host has updated.

# Search and useful headings

Search has one page entry plus H2-H4 section entries. Page text covers intro before first indexed heading; each heading text covers material until next indexed heading. Use informative headings and explanatory prose around tables/diagrams/code.

H1 is visible body, not a replacement for frontmatter route title. Keep them aligned. H2 rail uses at least two H2s; H3/H4 can be searchable without joining that rail. Copy built heading fragments rather than inferring punctuation or duplicate suffixes.

A useful procedure has purpose, prerequisites, complete steps, expected result and failure/recovery. A reference has exact field/default/limit comparisons. Many tiny duplicate pages are not more complete than one coherent task chapter.

# Add or reorganize safely

1. Select task audience and correct physical writer scope.
2. Write valid YAML, complete body and useful landing links.
3. Inventory existing paths/links before title or folder changes.
4. Preserve writer drafts and recoverable source/runtime/output.
5. Use supported Admin section rename when assignments must follow.
6. Build isolated output; fix YAML/collisions in source.
7. Inspect routes, sidebar, search, anchors, media and both themes/phone.
8. Release reviewed artifact; test old URLs and host redirects/removal.

File management and Sections and pages describe physical mutations, session effects and partial saves. Direct filesystem/Git moves do not automatically have the same account/draft effects. MarkStack does not enforce organization-wide review or redirect coordination.