Authoring brief — expansion phase (read fully before writing)

You are writing/uplifting Markdown pages for internal-developer-portal.com, an Eleventy static site for platform engineers, tech leads, internal dev-tool builders, and engineering managers. Niche: building internal developer portals (Backstage / Docusaurus / MkDocs), API catalogs, self-service platforms, RBAC/security, and developer experience.

Tone: implementation-first, concrete, practitioner. Match the existing pages — annotated config, real commands, version pins, ${ENV_VAR} placeholders for secrets. No marketing fluff.

Hard rules (do not violate)

  1. No YAML frontmatter. Each file begins with # Page Title (an H1). Metadata, breadcrumbs, and JSON-LD are generated automatically from the H1, first paragraph, and section structure.
  2. No external links. Only internal links to other pages on this site (and only those external URLs already present in existing source, which is none — so: internal links only).
  3. Code blocks must be fenced with a language (```yaml, ```bash, ```typescript, ```json), carry a version comment (e.g. # Requires Backstage >= 1.20.0), and use ${ENV_VAR} placeholders instead of hardcoded secrets.
  4. Tables must use left-aligned syntax: header row then | :--- | :--- |.
  5. Never use the words pillar, cluster, long-tail, hub and spoke, supporting page in reader-facing prose. (Domain uses like “Kafka cluster” are fine.)

Page anatomy by type

Pillar / section index (~2400–3000 words):

Cluster / sub-section index (~1700–2200 words):

Long-tail / how-to (~1200–1600 words):

Interlinking (mandatory)

Weave internal links inline into sentences at the first mention of a concept that has its own page — not as a bare list. Example: “align this with your OIDC & SSO Configuration strategy”. Minimums (inline, in prose, separate from the Related block): pillar ≥ 3, cluster ≥ 2, long-tail ≥ 1.

The ## Related block at the end is a short bulleted list. Always include the explicit up-link(s) to the parent page(s). Do not repeat in Related a link already used in the final prose paragraph.

FAQ format (so it renders as a toggle + becomes FAQPage schema)

## Frequently Asked Questions

**Is the question phrased like this?**

The answer is a separate paragraph on the line(s) below, after a blank line.

**Second question?**

Second answer.

A question is a paragraph that is entirely a bold string ending in ?. The answer is the following paragraph. Keep one blank line between them.

SVG diagram rules (a strict automated gate renders these in a browser — follow exactly)

Wrap every diagram like this:

<figure class="diagram">
<svg viewBox="0 0 880 360" role="img" aria-labelledby="SLUG-t SLUG-d" xmlns="http://www.w3.org/2000/svg">
<title id="SLUG-t">Short title</title>
<desc id="SLUG-d">One sentence describing what the diagram shows.</desc>
<defs>
  <linearGradient id="SLUG-grad" x1="0" y1="0" x2="1" y2="0">
    <stop offset="0" stop-color="#d98a79"/><stop offset="0.5" stop-color="#b25e78"/><stop offset="1" stop-color="#8f4f71"/>
  </linearGradient>
  <marker id="SLUG-arrow" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">
    <path d="M0 0 L9 4.5 L0 9 z" fill="#b25e78"/>
  </marker>
</defs>
<g font-family="Inter, sans-serif">
  <rect x="40" y="60" width="180" height="80" rx="12" fill="currentColor" fill-opacity="0.08" stroke="url(#SLUG-grad)"/>
  <text x="130" y="105" font-size="14" font-weight="700" fill="currentColor" text-anchor="middle">Box label</text>
  <path d="M220 100 H300" stroke="url(#SLUG-grad)" stroke-width="2.5" fill="none" marker-end="url(#SLUG-arrow)"/>
</g>
</svg>
<figcaption>One-line caption.</figcaption>
</figure>

Non-negotiable, or the gate fails:

Full site map (for interlinking — path → title)

Sections:

Architecture & Frameworks sub-sections:

Authentication, RBAC & Security sub-sections:

Plugin Ecosystem & Custom Extensions sub-sections:

Developer Experience & Self-Service Platforms sub-sections (all new):

Every page is created at content/<path>/index.md.