Astro Web Starter by Bryan Hogan

A free Astro starter template for building fast, accessible, content-first websites you fully own, authored by Bryan Hogan and distributed as an npm project generator.

What is the Astro Web Starter template?

The Astro Web Starter template is a boilerplate for Astro sites that pairs a Markdown/MDX content workflow with a small CSS design system and a single configuration file. You scaffold a project with npm create @bryanhogan/web-starter@latest, write content as .md or .mdx files, and the build outputs a static site with a sitemap, robots.txt, an RSS feed and per-post social images into dist/. It is created by Bryan Hogan and published on npm under the @bryanhogan scope.

Key Features

• Astro framework — pages are file-based routes in src/pages/; run npm run dev, npm run build (output in dist/) and npm run preview.
• Markdown and MDX content — create pages by adding an .mdx file to src/pages/ and blog posts by adding files to src/content/blog/, which are picked up automatically by listing pages.
• Single-file configuration — site name, description, author, production URL, social links, navigation and analytics live in src/config.ts.
• Layered CSS system — reset.css, var.css, global.css, util.css and markdown.css load in a fixed order; semantic tokens such as --color-background, --color-surface and --color-text map onto the Flexoki colour scale.
• Included components — buttons, heroes, cards, icons and navigation ship with the template and keep their own additional styles.
• Publishing basics — the build generates a sitemap, robots.txt, an RSS feed, page titles and descriptions, and structured data.
• Automatic blog social images — each blog post produces a 1200 × 630 PNG at dist/og/blog/<post-id>.png during the build rather than being committed as a source asset.
• Guided setup and CLI flags — the generator asks for directory, site name, description, author and production URL; --yes, --no-install and --no-git control non-interactive runs.

Who is it for?

• Developers starting a new site: scaffold a working Astro project in one command instead of assembling layouts, config and styles from scratch.
• Writers and bloggers: publish posts as Markdown in src/content/blog/ and rely on generated RSS, sitemap and social images.
• Teams wanting a clean base: take only the parts needed, such as the styles, layouts, header, footer or individual components.

What can you do with the Astro Web Starter template?

• Static hosting: build with npm run build and deploy the dist/ folder to any static host, including free options such as Cloudflare.
• Design customisation: re-map semantic colour tokens in var.css and review navigation, social links and social image settings before publishing.
• Content migration: replace the example assets in public/ (notably favicon.svg and og-default.png) and edit or replace the example pages in src/pages/.

How does the setup work?

Install Node.js 22.12.0 or newer, Git and an editor such as VS Code or Zed, then run npm create @bryanhogan/web-starter@latest. The guided prompts create the project directory, write site details to src/config.ts, optionally install dependencies and optionally run git init. Running npm run dev serves the site at http://localhost:4321 (Astro picks another port if 4321 is busy).

FAQ

Is the Astro Web Starter template free?

Yes. The template is described as a free Astro starter, and you own the code and can change every part of it.

What Node.js version does it require?

Node.js 22.12.0 or newer, along with npm, which ships with Node.js. Git is also required for the recommended setup.

Can I remove MDX support?

Yes. Convert or remove every .mdx page and post, run npm uninstall @astrojs/mdx, then remove the mdx() integration from astro.config.mjs.

Where do I change site details?

Everything sits in src/config.ts: site name, description, author, production URL, social links, navigation and analytics. With --yes, the URL defaults to https://example.com and must be replaced before publishing.