Next.js content sites
How the portal renders blog posts, docs, and notes with server-side Markdown.
Purpose
How the portal renders blog posts, docs, and notes with server-side Markdown.
This guide is part of the Julian Wiley Portal documentation set. The project is the public Next.js site that hosts project writing, notes, docs, and an auth-gated admin view of the homelab. Use this page when you need enough context to understand the design before changing code, manifests, configuration, or operational runbooks.
Where it fits
Repository: julianwiley-portal
Audience: readers who want the narrative, reference material, and deployment details behind the larger workspace.
Main technologies: Next.js 15, React 18, TypeScript, Ant Design, Pro Components, NextAuth, gray-matter, react-markdown, Docker, GHCR, Kubernetes, Cloudflare Tunnel.
The implementation should be read as a set of boundaries rather than a pile of tools. Configuration declares what should exist, runtime services perform the work, persistence layers keep durable state, and observability explains what happened after the fact.
Implementation pattern
- Identify the durable resource: table, topic, deployment, agent spec, bot spec, manifest, or content page.
- Find the wrapper or runtime responsible for it instead of bypassing the project contract.
- Add configuration in the narrowest location that can express the new behavior.
- Add a smoke test or runbook step that proves the change can be recovered.
- Document the operational owner and the failure mode that matters most.
Operational checks
| Check | Why it matters |
|---|---|
| Configuration is explicit | Rebuilds and restarts should not depend on memory. |
| State has one owner | Competing writers make recovery hard. |
| Logs and progress are visible | Long-running workflows need user trust. |
| Backups or rebuild steps exist | A local-first system still needs disaster recovery. |
| Links to related docs are current | The portal is the public index for the workspace. |
Extension notes
When extending this area, prefer the project's existing factory, registry, wrapper, or runtime pattern. That keeps new work compatible with the surrounding code and avoids a second hidden implementation of the same idea.