D4rk Notes Project

Overview

D4rk Notes is a Next.js publishing site for technical notes and project writeups.

The important part is the content flow: articles live as MDX files on disk, the app reads them at runtime, and the public pages are set up to render dynamically instead of staying frozen at build time.

What It Does

• Serves the homepage, category pages, and article pages from filesystem content
• Reads articles from mounted content/ and blogfiles/ directories
• Parses frontmatter with typed validation
• Extracts headings for the table of contents
• Uses a lightweight search API over the loaded article set
• Keeps the public site and the editor/admin flow separate

Architecture

The app runs as a production Next.js container in Docker Compose. The compose file maps port 3034, mounts ./content and ./blogfiles, and runs the site from the ghcr.io/dhaevyd/d4rknotes:0.1.3 image.

The content layer is filesystem-based. lib/content.ts reads MDX with gray-matter, validates frontmatter with Zod, and loads articles from both mounted directories. The homepage, category pages, and article pages are marked dynamic so they pick up file changes on request.

Admin and Workflow

There is a protected /shogun area backed by GitHub auth. The middleware guards the admin and admin API routes, and the admin shell shows the signed-in GitHub user.

The repo also has an MDX preview endpoint, a search endpoint, and a content validation script. That keeps the workflow small but still usable: edit the MDX, validate it, and let the site read it directly.

Current Status

• The site is live
• Runtime MDX reads are enabled
• The admin/auth path is in place
• The article set is built for quick content updates without a rebuild loop for every text change

Roadmap

Search polish, editing workflow hardening, deployment hardening, and later RAG or graph features can still come next.