Infraze — Documentation & Engineering Notebook Platform
LiveThe site you're reading: a static Astro/MDX knowledge base with a structured documentation engine, reading-time and related-post trust signals, full-text search, RSS, and automated SEO — deployed on Vercel.
Problem
I needed a single place to publish Azure platform documentation, architecture decisions, and engineering write-ups that reads like a practitioner's reference rather than a generic developer portfolio. Off-the-shelf blog themes mixed marketing patterns with content and made the documentation a second-class citizen.
Architecture
Astro in static output mode generates the entire site at build time. Content lives in typed content collections (blog, docs, authors, projects) validated by Zod schemas, so a malformed post fails the build instead of shipping broken. Tailwind CSS handles styling; Pagefind provides static full-text search; the @astrojs/sitemap and a custom RSS endpoint handle discovery. Vercel builds and serves the static output behind security headers and permanent redirects defined in vercel.json.
Requirements
- Clear separation of documentation (implementation detail), blog (reasoning and lessons), and projects (case studies).
- Fast, static delivery with strong SEO defaults (sitemap, RSS, JSON-LD, OpenGraph) and no client-side runtime cost for content pages.
- Reader-trust signals: reading time, last-updated dates, related articles, and a clear author identity.
- Maintainable content authoring in MDX with reusable components (admonitions, tabs, Mermaid diagrams).
- A single source of truth for identity and credibility so author/social/credential data never drifts between pages.
Implementation
- Modelled blog, docs, authors, and projects as separate content collections with strict frontmatter schemas in content.config.ts.
- Built a reusable documentation template (Purpose → Design Reasoning → ADR → Recommended Configuration → Example → Validation → Common Mistakes → References) used across the Azure Platform Foundation doc set.
- Centralised author identity, certifications, and social links in siteData so the homepage, About page, footer, and author cards all render from one place.
- Added trust signals: computed reading time, related-post matching by shared tags, end-of-post author cards, and last-updated dates.
- Wired build-time SEO: per-page metadata, JSON-LD, an auto-generated sitemap, and an RSS feed.
Lessons learned
- Schema-validated content collections catch authoring mistakes (wrong frontmatter keys, missing fields) at build time — the same 'fail fast at the boundary' principle as Azure Policy on a platform.
- Treating documentation, blog, and projects as distinct content types — rather than one blog with tags — keeps the information architecture honest as content grows.
- A single source of truth for identity removed an entire class of drift where the name, role, or links disagreed between pages.
Future improvements
- Publish the Bicep/Terraform behind the Azure Platform Foundation docs as a companion repository and link each doc to its module.
- Add a reference-architecture and decision-record (ADR) index as first-class, browsable sections.
- Introduce an explicit series/collection model so multi-part write-ups link automatically instead of by hand.