+----------------------------------------------------------------------------------+
|      _  __    ____ __  __   ______ _  __  ___     __  ___ ____   __     ______   |
|     | |/ /   / __ )\ \/ /  / ____/| |/ / /   |   /  |/  // __ \ / /    / ____/   |
|     |   /   / __  | \  /  / __/   |   / / /| |  / /|_/ // /_/ // /    / __/      |
|    /   |   / /_/ /  / /  / /___  /   | / ___ | / /  / // ____// /___ / /___      |
|   /_/|_|  /_____/  /_/  /_____/ /_/|_|/_/  |_|/_/  /_//_/    /_____//_____/      |
|                                                                                  |
+----------------------------------------------------------------------------------+

A template for building "X by Example" websites — hands-on introductions to a programming language through annotated example programs, in the style of gobyexample.com.

Built with Astro and Tailwind CSS v4.

Features

• Two-column examples: explanation on the left, code on the right, aligned segment by segment (stacks on mobile)
• Markdown-driven: examples are plain .md files in a content collection
• Categories: optionally group examples on the index page
• Dark/light mode: nightfox palettes (dawnfox/terafox) for both the site and syntax highlighting, persisted to localStorage
• Batteries included: Shiki syntax highlighting, Fontsource fonts (Karla + JetBrains Mono) via Astro's font provider, Lucide icons, ESLint + Prettier

Quick start

npm install
npm run dev

Make it yours

1. Site config — edit src/consts.ts (SITE_TITLE, SITE_DESCRIPTION, SITE_AUTHOR, GITHUB_URL).
2. Content — replace the files in src/content/examples/ with your own (see below).
3. Theme — swap the palettes in src/plugins/shiki-themes.mjs and the CSS variables in src/styles/global.css.
4. Favicon & social image — replace public/favicon.svg and public/og-image.png (source in public/og-image.svg) with your own.
5. Deployment — set site (and base if needed) in astro.config.mjs, and update the Sitemap: URL in public/robots.txt to match. site is also used to generate canonical URLs and Open Graph tags. Ships configured to deploy to Cloudflare Workers (see wrangler.jsonc — update name to match your project, then npm run deploy); swap or remove the @astrojs/cloudflare adapter in astro.config.mjs for another target.

Writing examples

Each example is a Markdown file in src/content/examples/:

---
title: Hello World
order: 1
category: Basics # optional
---

Explanatory text goes here. The code block that follows a block of text is
rendered beside it in the right column.

​`js
console.log("hello world");
​`

More text, then more code — each pair becomes a row.

Frontmatter fields:

Field	Required	Purpose
title	yes	Page title and index link text
order	yes	Sort order (also drives prev/next navigation)
category	no	Group heading on the index page; omit for no group

Use the language's code fence (```rust, ```python, …) for correct syntax highlighting.

Commands

Command	Action
npm run dev	Start dev server at localhost:4321
npm run build	Build production site to ./dist/
npm run preview	Preview the production build locally
npm run lint	Lint with ESLint (lint:fix to autofix)
npm run format	Format with Prettier (format:check to CI)
npm run deploy	Build and deploy to Cloudflare Workers

Contributing

See CONTRIBUTING.md.

License

MIT — use it however you want, just keep the license notice.