Skip to content
Loop & Lede

    Navigate ↑↓ · Open ↵ · Close esc

    · 2 min read

    Setting Up This Blog

    A minimal startup guide for running, building, and previewing this Astro blog locally.

    This is the blog you are reading, and this post is the setup guide for it — the commands a developer needs the first time they clone this repository and want to run it locally.

    Requirements

    • Node.js 22.12 or newer. The exact version is pinned in .nvmrc; if you use nvm, running nvm use in the project root switches to it automatically.
    • npm — it ships with Node, no separate install needed.

    Install dependencies

    From the project root:

    npm install

    This reads package-lock.json and installs everything into node_modules/.

    Run the dev server

    npm run dev

    Starts Astro’s dev server, by default at http://localhost:4321. It watches every file under src/ and reloads the browser on save — including content in src/content/blog/, so a new post or an edit to an existing one shows up immediately.

    Type-check the project

    npm run check

    Runs astro check, which type-checks .astro files and validates content collection frontmatter against the schemas in src/content.config.ts. Worth running before a build if you have changed frontmatter, component props, or TypeScript logic.

    Lint and format

    npm run lint

    Runs ESLint across the project.

    npm run format

    Runs Prettier and rewrites files in place.

    Build for production

    npm run build

    Produces a static site in dist/. There is no server runtime — the output is plain HTML, CSS, and a small amount of JS for progressive enhancement (dark mode, the copy-code button, the command palette). This is the command a deploy pipeline should run.

    Preview the production build

    npm run preview

    Serves the contents of dist/ locally, exactly as it would be served in production. Use this to sanity-check a build before deploying — npm run dev runs different code paths (unbuilt, with draft posts visible) and is not a reliable stand-in for this step.

    Where things live

    • Posts: src/content/blog/*.md or *.mdx — the frontmatter schema is documented in docs/content.md in the repository.
    • Site identity, navigation, forms, analytics: src/config.ts — documented in docs/customization.md.
    • Colors, fonts: src/styles/global.css, inside the @theme block.
    • Deploying: docs/deploy.md in the repository.

    That’s the whole loop: npm install once, npm run dev while writing, npm run build and npm run preview before shipping.