Documentation architecture

This documentation is MDX-driven. Articles live as files, navigation is declared as data, and the portal derives tables of contents, previous/next links and the search index from those two sources.

Directory layout

content/docs/
  overview.mdx
  getting-started.mdx
  getting-started/
    contact.mdx
    engagement-process.mdx
  company/
    brand.mdx
  services/
    penetration-testing.mdx
  guides/
    contact-form-integration.mdx
lib/
  docs.ts
app/docs/[[...slug]]/page.tsx

Frontmatter

Each article begins with a small frontmatter block:

---
title: Assessment scope & authorization
description: Authorization, scoping and rules-of-engagement requirements.
status: Published
---

title and description populate the page header, metadata and search index. status is either Published or Placeholder, and is shown as a label in the article header — placeholders are visibly marked rather than silently incomplete.

Navigation

The sidebar tree is declared explicitly in lib/docs.ts:

export const DOC_NAV = [
  {
    title: "Getting started",
    items: [
      { title: "Introduction", slug: "getting-started" },
      { title: "Engagement process", slug: "getting-started/engagement-process" },
    ],
  },
];

Ordering is intentional rather than alphabetical, and article titles in the sidebar can differ from the H1 where a shorter label reads better.

Adding an article

1. Create the MDX file at the path matching its slug.
2. Add an entry to the relevant group in DOC_NAV.
3. Run the build. The route is generated from the navigation list; no dynamic registry is maintained by hand.

Tables of contents

Headings are extracted from the source at render time: level-two headings become the right-hand table of contents, and level three appears as an indent where present. Anchor ids are generated by rehype-slug, and the scroll-tracking component highlights the section currently in view.

Code fences are skipped during extraction, so a ## inside a code block will not appear in the TOC.

Search

The search index is built from the navigation list, frontmatter and extracted headings — no external service is required. The dialog supports Cmd/Ctrl + K, arrow-key navigation and Enter to open the highlighted result.

Custom components

Three components are available inside articles:

<Callout title="Authorization is not optional" tone="warning">
  Testing requires written approval.
</Callout>

<Steps items={[
  { title: "Discovery", body: "Understand the problem." },
  { title: "Scope", body: "Agree what is included." }
]} />

<CodeBlock language="ts" code="const answer = 42;" />

Callout tones are note, warning and draft. Code blocks rendered from fences automatically gain the copy control.

Writing conventions

• Use ## for sections that belong in the table of contents; avoid skipping levels.
• Keep paragraphs short; documentation is scanned before it is read.
• Prefer concrete examples over descriptions of examples.
• Mark unconfirmed detail as a placeholder instead of filling the gap with plausible text.