Project Structure

Linear Content is a Quarto-based technical blog.

Directory Layout

linear-content-v2/
├── _quarto.yml        # Site configuration
├── _brand.yml         # Brand colors, typography
├── theme-dark.scss    # Bootstrap dark mode overrides
├── styles.css         # Custom CSS
├── index.qmd          # Homepage with post listing
├── about.qmd          # About page
├── posts/             # Blog posts (one folder per post)
├── fonts/             # Berkeley Mono woff2 files
├── images/            # Site images
├── pending/           # Draft posts (not published)
├── scripts/           # Build/utility scripts
└── docs/              # Developer documentation
    ├── STRUCTURE.md   # This file
    ├── VISUAL_IDENTITY.md
    └── history/       # Archived implementation notes

Key Files

File Purpose
_quarto.yml Site metadata, navbar, footer, format options
_brand.yml Color palette, typography definitions
theme-dark.scss Bootstrap Sass variable overrides for dark mode
styles.css All visual styling (dot grid, tick marks, etc.)
index.qmd Post listing configuration
docs/history/ Archived implementation notes and specs

Adding Posts

Create a folder in posts/ with an index.qmd:

posts/
└── my-new-post/
    ├── index.qmd      # Post content
    └── images/        # Post-specific images (optional)

Post frontmatter:

---
title: "Post Title"
description: "Brief description"
date: "2024-01-15"
categories: [nlp, data science]
---

Building

quarto preview          # Local dev server
quarto render           # Build to _site/

Adding Viz Posts

The study system produces complete post folders. To publish:

  1. Copy the folder (e.g., 20260103_llm-resampling/) into posts/
  2. Edit index.qmd frontmatter if needed (title, description, categories)
  3. Run quarto preview to verify

Viz Post Structure

posts/
└── 20260103_llm-resampling/
    ├── index.qmd          # Quarto wrapper (generated by study system)
    └── viz/
        ├── app.html       # HTML fragment (no doctype/html/head/body)
        ├── style.css      # Scoped CSS using blog variables
        ├── main.js        # D3 visualization
        └── viz_data.json  # Data file

Key Points

  • app.html must have no indentation (or Quarto converts it to code blocks)
  • CSS uses blog variables (--black, --paper, etc.) for automatic dark mode
  • The resources field in frontmatter ensures viz_data.json is copied to build

CSS should use blog variables (--black, --paper, --mid-gray, --border-color, --code-bg) for automatic dark mode support. See VISUAL_IDENTITY.md for the complete design system.

Design System

See VISUAL_IDENTITY.md for colors, typography, and styling guidelines.