Skip to main content

Colophon

This page explains how southpawriter.com is built, why it's built that way, and where to find the documentation that predates the code.

The Stack​

Static site generator: Docusaurus 3.9.2 with the v4 future compatibility flag enabled. The classic preset provides docs (sidebar-driven), blog (chronological, tag-based), and standalone pages. It also generates RSS and Atom feeds automatically.

Hosting: Static files. No server-side rendering, no database, no CMS. The site builds to a flat directory of HTML, CSS, and JavaScript that can be served from anywhere.

Styling: Custom CSS built on top of Docusaurus's Infima framework. The entire color palette derives from the brand's SVG assets: terminal dark grey (#2a2a2a), accent orange (#FF8C00), and traffic-light green (#28c840). Dark mode is the "native" look; light mode uses the same orange accent against a warm near-white surface.

Code highlighting: Prism via prism-react-renderer, using the synthwave84 theme in dark mode (with the background overridden to match the terminal surface color) and github in light mode. C#, Bash, JSON, and Markdown are explicitly loaded as additional languages.

Typography: JetBrains Mono for headings, navigation, code blocks, and all terminal UI elements, chosen for its excellent ligatures and readability at small sizes. Body text uses Inter, a typeface designed specifically for screen readability. Both are loaded via Google Fonts with system fallbacks ('Courier New', Consolas, monospace for mono; system-ui, -apple-system, sans-serif for body).

The Terminal Aesthetic​

The site's visual identity is a terminal emulator: dark backgrounds, monospace type, orange accent color, and UI elements that reference macOS terminal windows (traffic-light dots, title bars with shell prompts, blinking cursors).

This isn't just decoration. The terminal metaphor reflects what the site is about: a technical writer who works at the command line, building developer tools and researching how AI interacts with the web. The aesthetic should feel familiar to the kind of person who'd be interested in the content.

Key visual elements:

  • Terminal-framed hero on the homepage, with traffic-light dots and a ryan@southpawriter ~ $ prompt in the title bar
  • Blinking orange cursor (█) after major page headings via CSS ::after pseudo-elements
  • Custom 404 page styled as a bash: cd: No such file or directory error, complete with shell prompt and recovery suggestions
  • Terminal-card feature sections on the homepage, where each feature card has its own mini title bar with a path like ~/tech-writing
  • Admonitions restyled as terminal output blocks with [INFO], [TIP], [WARN], and [ERR] prefixes
  • Reading progress bar, a thin orange gradient bar fixed to the top of the viewport that fills as you scroll

The Documentation-First Approach​

Every page on this site was specified in a Markdown file before any code was written. This isn't an aspiration; it's literally how the site was built:

  1. Content strategy document defined the site structure, page types, tag taxonomy, and cross-referencing rules before any pages existed
  2. Migration plan mapped exactly which files would move where, what config changes were needed, and what the build verification steps would be
  3. Guides like the Docs-First Workflow were written as documentation about the process that was being followed to write them

This recursive quality is intentional. The site is both the subject and the demonstration of documentation-driven development.

The llms.txt Dogfooding​

This site serves its own llms.txt file: a structured, machine-readable summary of the site's content designed for AI consumption. This is the exact format being researched across the rest of the project.

The file lives in Docusaurus's /static directory, which means it's served verbatim at the site root (southpawriter.com/llms.txt) with no processing or transformation. It's maintained manually and updated whenever new pages are added. The Adding llms.txt to a Docusaurus Site guide documents this exact setup.

Serving our own llms.txt while simultaneously researching whether anyone reads them is, admittedly, a bit like leaving cookies out for Santa while writing a paper about whether he exists. But the research value comes from the process of maintaining it, not from whether an AI system actually fetches it.

The SVG Pipeline​

All project logos and brand assets are hand-crafted SVGs. The pipeline:

  1. Design in a vector editor (typically Figma or Illustrator)
  2. Optimize for web delivery (clean paths, minimal groups, no embedded fonts)
  3. Store in the repository at static/img/ (brand assets) and static/img/projects/ (project logos)
  4. Reference via standard <img> tags or Webpack's SVG-as-React-component import for inline rendering

The social card (southpawriter-social-card.jpg) is a rasterized version of the terminal-style SVG source, sized at 1200x675 for OpenGraph compatibility.

The Three Pixel-Art Characters​

The homepage features three retro pixel-art SVG illustrations, a recurring bald, bearded, bespectacled character in different emotional states:

  • Scribbling furiously (the Tech Writing pillar)
  • Cursing at an LLM (the AI Research pillar)
  • Calmly shipping code with a smirk (the Dev Tooling pillar)

These are the same character in different contexts, which is the point. Technical writing, AI research, and developer tooling aren't three separate disciplines here. They're three moods of the same person.

Source and Licenses​

The site source is maintained in a private GitHub repository. The content (blog posts, documentation, guides) is original work by Ryan Goodrich. The Docusaurus framework is MIT-licensed. Brand assets and project logos are proprietary.

If you're curious about any specific implementation detail, the Docs section has the reference material, and the Blog has the narrative behind the decisions.