Skip to main content

Index Page Standard

What should every /playbook index page help the reader decide first?

An index page is a decision surface. It helps a reader choose the next page, path, model, or bet. If the page teaches for too long before it routes, the index has become a shelf.

Core Rule​

Route before teaching.

Do not use index.mdx without subpages. Do not create a folder plus index.mdx for a standalone page. Make a single concept a named page instead, such as industry-meta.mdx. If the route stays as an index, it must front real subpages and earn that shape as a FACT hub: opening, visual, insight, definition, and application links that route into the child pages.

The first screen must answer three questions.

  • Why am I here? State the page job in one direct sentence.
  • Where can I go? Show the highest-value paths before long explanation.
  • How do I choose? Give the reader a filter: role, need, edge, layer, question, or proof state.

Move theory, history, philosophy, and deep examples into child pages.

Page Types​

Index pages still follow their frontmatter type.

  • Hub index — orient and route. Use a short spine. Do not teach.
  • Domain-map index — help the reader choose inside a territory. Use forces, players, layers, value-chain positions, or opportunity filters.
  • Concept index — explain one reusable model, then route to applications, examples, checks, and deeper references.
  • Template index — show which template to use when, with the payoff for each choice.

The type chooses the structure. The route chooses the terrain.

First Screen​

Use one of these patterns before the fold.

  • Start paths — for broad hubs.
  • By need — for readers who know their job.
  • By edge — for opportunity, industry, or investment pages.
  • By role — for team, agent, or workflow pages.
  • By layer — for systems, platform, data, and architecture pages.
  • By proof — for evidence, claims, and capability pages.

Every link needs scent. The reader should know why to click before clicking.

Bad:

- [AI](/playbook/ai/)

Better:

- [AI](/playbook/ai/) — use models, agents, instruments, and proof to turn cognition into action.

Move Depth​

When an index grows, split it.

  • Keep the index as the front door.
  • Move deep theory to *-meta, principles, or a child concept page.
  • Move repeated action to how-to-* or a playbook.
  • Move long reference lists to reference-*.
  • Move proof and source-backed claims to an evidence page.

The Industries pattern is the model: the index is the finder; Industry Meta holds the deeper theory.

FACT Shape​

When an index is a FACT hub, it follows this order.

  1. Opening — a question or conviction that names why the concept matters.
  2. Visual — a video, image, diagram, matrix, or component that validates the page's authority.
  3. Insight — one or two sentences that sell the content below.
  4. Definition — what the concept is, in tight language.
  5. Application — links to the child pages.
  6. Context — three to six links with reasons to click.

If there are no child pages to route toward, the page is not an index. Move it to a named concept page.

Apply It​

Use this sequence when rewriting any /playbook/**/index.md or /playbook/**/index.mdx.

  1. Name the reader's decision.
  2. Declare the page type and template before editing.
  3. List every content chunk.
  4. Keep route-setting chunks on the index.
  5. Move teaching-heavy chunks to child pages.
  6. Add scented links to the paths that remain.
  7. End with one concrete next action or question.
  8. Regenerate projections when the edit adds, removes, or retypes docs pages.

Checks​

An index passes when these checks are true.

  • The page job is clear in five seconds.
  • The route is a real front door: it has child pages to route toward.
  • The first screen offers a useful route or shortlist.
  • Every route has scent.
  • The page explains how to choose, not only what exists.
  • Long theory has a child home.
  • The final section asks for a concrete next action.
  • The page stands without private project context.

Failure Modes​

  • Shelf page — the index lists everything but helps no one choose.
  • Theory wall — the reader must read the model before they can pick a path.
  • Flat catalog — links appear without scent, priority, or decision logic.
  • Type drift — frontmatter says hub, but the body teaches like a concept page.
  • Projection drift — generated maps are stale after adding or retyping pages.
  • Private leak — the page depends on project state or internal paths to make sense.

Context​

Questions​

Which index pages are still shelves instead of decision surfaces?

  • Which pages teach before they route?
  • Which indexes need a *-meta child page?
  • Which generated projections must be refreshed after the next rewrite?