A free Astro starter template for good, fast and accessible websites you fully control.
Write your content simply in Markdown or MDX, change the colors, text and other styling, then publish the finished site anywhere. You own the code and can change every part of it.
This project contains the boilerplate I use for every website I build. You can use everything or just parts of it.
- Easily create pages: You can create pages using simple Markdown. Just add a
.mdxfile tosrc/pages/. - A ready-to-use blog: Add Markdown or MDX posts to
src/content/blog/. They are automatically included in relevant lists. - Simple CSS base: Change shared colors, fonts, and spacing in one file.
- Useful components: Buttons, heroes, cards, icons, navigation, and more are included.
- Search and sharing basics: Page titles, descriptions, structured data, and automatic blog social images are ready.
- Publishing basics: The starter creates a sitemap,
robots.txt, and an RSS feed. - Responsive and accessible defaults: The layout works across all screen sizes and includes accessibility considerations.
- One settings file: Change site details, social links, and everything you need in just one file:
src/config.ts.
Setup video is currently being adjusted.
Quick summary: Install Node.js, Git and VSCode. Run npm create @bryanhogan/web-starter@latest and go through the setup. Run as npm run dev for testing, might need to fix execution policy. Initialize repository and connect to GitHub. Adjust the config.ts file. Adjust relevant pages. Add to static site host.
Detailed setup explanation:
Before you begin, install:
- Node.js 22.12.0 or newer. Check with
node --version. You will also need npm, which is included with Node.js. - Git
- A way to edit your files, e.g. Visual Studio Code or Zed.
Run the guided setup:
npm create @bryanhogan/web-starter@latestThe command downloads and runs the project generator; you do not need to clone this repository first. It asks for:
- The directory in which to create the project
- The site name, description, author, and optional production URL
- Whether to install dependencies with npm
- Whether to initialize a Git repository
When setup finishes, follow the commands shown in the terminal to enter the project directory and start Astro. Your local site will be available at http://localhost:4321 (after using npm run dev).
Command-line options and non-interactive setup (totally optional)
You can provide the destination directory in the command. For example, this creates my-website inside the current directory and accepts all default answers:
npm create @bryanhogan/web-starter@latest my-website -- --yesOptions placed after -- are passed to the generator:
| Option | Effect |
|---|---|
--yes |
Skip the questions and use the defaults. |
--no-install |
Create the project without running npm install. |
--no-git |
Create the project without running git init. |
With --yes, the site name is derived from the directory name and the production URL is set to https://example.com. Replace the placeholder values in src/config.ts before publishing.
When setup finishes, enter the project directory and start Astro:
cd my-website
npm run devIf you chose not to install dependencies during setup, run npm install before npm run dev.
The guided setup writes the basic information to src/config.ts.
You might want to add your social media profile links and other content such as an analytic link to the config.ts file. Review the navigation, social links, and social image settings before publishing.
Also replace the example assets in public/, especially favicon.svg and og-default.png, when you are ready to use your own branding. The default social image is used by regular pages; blog posts generate title-based images automatically during the build.
See How to configure config.ts for every available field.
npm run devAstro shows a local address in the terminal, normally http://localhost:4321. Open it in your browser. Your changes appear while the server is running.
Windows might tell you that the execution policy is not set, run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser on the powershell as an administrator to fix that.
Press Ctrl + C in the terminal to stop the server.
If port 4321 is already in use, Astro selects another port; use the exact URL printed in the terminal.
- Edit or replace the example pages in
src/pages/. - Add blog posts to
src/content/blog/. - Add processed images to
src/assets/images/or static files topublic/. - Update the header and footer navigation links in
src/config.tswhen your page structure changes.
There are many places where you can host your new static site for free, e.g. Cloudflare.
npm run build
npm run previewCommands for this project
| Command | Purpose |
|---|---|
npm run dev |
Start the local development server. |
npm run build |
Generate the production site in dist/. |
npm run preview |
Preview the generated production build. |
npm run astro -- <command> |
Run an Astro CLI command. |
- How to configure
src/config.ts - How to create Astro and MDX pages
- Customizing the design
- Component showcase
- Markdown style guide
You can use the entire project or take only the pieces you need, such as the styles, layouts, header, footer, or individual components.
About MDX support
The Astro MDX integration lets you use Astro components inside Markdown-like pages.
To remove MDX support:
- Convert or remove every
.mdxpage and blog post. - Run
npm uninstall @astrojs/mdx. - Remove the
mdx()integration fromastro.config.mjs.
About the automatically generated blog social preview images
Each blog post also generates a 1200 × 630 social image at dist/og/blog/<post-id>.png. These files are build output rather than source assets, so they do not need to be added to public/ or committed to Git.
Details on the CSS setup
The project loads its CSS in this order:
reset.cssremoves browser defaults the template does not use.var.cssdefines color, typography, spacing, layout, border, shadow, and other design tokens.global.cssapplies site-wide element styles and responsive typography.util.cssprovides layout, flow, accessibility, flex, margin, and padding utilities.markdown.cssstyles rendered Markdown and MDX prose.
The shared layouts load these files for you. Each component keeps its own extra styles.
Colors use a subset of Flexoki's neutral scale with its original numbering: 50, 100 through 900 in steps of 100, and 950; chromatic scales run from 100 to 900. Components use semantic tokens such as --color-background, --color-surface, and --color-text. Adjust these mappings in var.css to customize each theme. The template uses neutral 950 for the dark background and 50 for the light background, with surfaces at 900 and 100 respectively.
For more background, see the Clean Web Dev Guide.
Project folder guide
src/
├── assets/images/ Images processed by Astro
├── components/ Reusable Astro components
├── content/blog/ Markdown and MDX blog posts
├── layouts/ Shared page and post layouts
├── pages/ File-based website routes
├── styles/ Global design system and prose styles
├── config.ts Site-wide configuration
└── content.config.ts Blog collection schema
public/ Static assets copied as-is
- Add deployment guides for common static hosting providers. And make a Video setup guide.
- Using the Astro framework
- Built as described on Clean Web Dev Guide
- Built by Bryan Hogan
- Using the Flexoki color palette with custom semantic theme mappings.