Diagram Chasing story scaffold

Start a new Diagram Chasing data story from this scaffold. It provides SEO, a footer with the latest posts, analytics, basepath handling, deploy workflows, and a project bootstrap script, so you can focus on the design and visualization work for each story.

Before you begin

• Install pnpm.
• Install the GitHub CLI and run gh auth login.
• Install the Netlify CLI and run netlify login.

Start a story

1. Create a project from the scaffold and install dependencies:

   npx degit diagram-chasing/svelte-starter my-story
   cd my-story
   pnpm install

2. Run the setup script:

   pnpm setup

   The script prompts you for the story details and then:

   • Rewrites story.config.js and the package name.
   • Creates the GitHub repo and pushes. The repo is private by default; pass --public to override.
   • Creates the Netlify site and links the local checkout.
   • Sets the NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID Actions secrets. The token is a one-time personal access token cached in ~/.config/diagram-chasing/.
   • Offers to append the proxy line to the sibling ../site/_redirects.

   Pass --dry-run to print every mutating command without executing it. The script is idempotent: if it fails partway, fix the cause and run it again.

3. Complete the remaining manual steps:

   1. Commit and deploy the studio site repo to activate the proxy.
   2. Replace static/og/card.jpg with the real share card.
   3. Set publishTime in story.config.js when the story launches.
   4. After the story's post exists in the studio site repo, run pnpm sync-standard-site there and copy the atproto: URI it writes into atprotoDocument in story.config.js. This gives the story a "View publication" button on Bluesky.

Develop the story

• pnpm dev: Start the dev server. No basepath is needed locally.
• pnpm build: Refresh redirects and latest posts, build the site, then inject the Standard.site link tags.
• pnpm preview: Serve the build. Visit /YYYY/slug, including the basepath.
• pnpm rss: Refresh the footer's latest-posts JSON.
• pnpm check: Run svelte-check.

Deploy the story

Push to main to trigger a Netlify preview deploy. Run the Production Deploy action to deploy to production. Both workflows accept workflow_call, so a data-refresh cron can chain a deploy.

What to customize

Change freely:

• Design tokens in src/app.css, including colors and the --font-sans and --font-heading hooks.
• Fonts.
• The story content in src/lib/content.md.
• Chart components in $charts and data in $data.
• The UI kit in src/lib/components/ui/.

Keep as-is:

• The shape of story.config.js.
• src/lib/site.ts, SEO.svelte, and Footer.svelte. Restyle Footer.svelte through the shared tokens instead of rewriting it.
• scripts/, .github/workflows/, and netlify.toml.
• The paths: { base, relative: false } block in svelte.config.js, which keeps asset URLs working behind the proxy.

For the full contract and pointers to advanced patterns such as data pipelines, crons, and per-page OG images, see CLAUDE.md.