Skip to content

Static site generators: create, run and build

Every static site generator follows the same loop: install a toolchain, scaffold a project, run a dev server while you write, build to a folder of HTML, CSS and JavaScript, and upload that folder to a host. What differs is the language runtime, the content model and the name of the output folder. This page gives the working commands for eight popular generators, side by side, so you can pick one and get it running. The static websites overview explains when a static site is the right choice in the first place.

Versions were checked on npm, PyPI, RubyGems and the projects’ Git tags in November 2026. The MkDocs, VitePress and Next.js builds below were run in a sandbox (Python 3.11, Node.js 22.23.4); the other command sequences come from each project’s own getting-started guide and were not run here because the toolchain (Go, Ruby) was not available or the install is very large. The example content is an invented OrdersPortal documentation site.

Generator Runtime Build output Best known for
Astro Node.js 22.23.4+ dist/ Content sites with islands of interactivity
Next.js static export Node.js 20.9+ out/ React apps that can be fully prerendered
Hugo Single Go binary public/ Very fast builds of large sites
Jekyll Ruby _site/ Blogs, and the GitHub Pages heritage
Docusaurus Node.js 20+ build/ Versioned product documentation in React
VitePress Node.js 18+ docs/.vitepress/dist/ Fast Vue-based documentation
MkDocs Python 3.8+ site/ Markdown documentation for Python teams
Gatsby Node.js 18 to 25 public/ React sites with a GraphQL data layer

Astro 7 (7.4.12 at the time of writing) renders pages to HTML at build time and ships no JavaScript unless a component opts in with a client:* directive. It is the generator behind this site. Astro needs Node.js 22.23.4 or later. The create astro wizard scaffolds the project; npm run dev serves it on port 4321; npm run build writes the static site to dist/; and npm run preview serves that build locally. Adding an adapter turns individual routes into server-rendered ones, so a site can start static and grow.

Terminal window
npm create astro@latest orders-docs
cd orders-docs
npm run dev # http://localhost:4321
npm run build # static output in dist/
npm run preview # serve dist/ locally

The Astro section covers it in depth: introduction and setup, pages, layouts and content, and integrations, build and deploy.

Pitfalls:

  • An older Node.js 22. Astro 7.4.2 and later refuse to install on Node.js 22 releases before 22.23.4; pin the version in CI.
  • Project sites without base. On a GitHub Pages project site, set site and base or every asset path breaks.

Next.js (16.4.6 on npm) is a React framework that normally runs on a Node.js server, but with output: 'export' in next.config the production build writes a fully static site to out/. The separate next export command was deprecated in 13.3 and removed in Next.js 14; next build does the export. Server Components still run, but only at build time, and dynamic routes must list their parameters with generateStaticParams().

Features that need a server at request time are not supported in an export: cookies, rewrites, redirects and headers from next.config, Proxy (formerly middleware), Incremental Static Regeneration, Server Actions, Draft Mode, dynamic routes without generateStaticParams(), and image optimization with the default loader.

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
trailingSlash: true, // /orders/1001/ -> out/orders/1001/index.html
};
export default nextConfig;
app/orders/[id]/page.jsx
export function generateStaticParams() {
return [{ id: '1001' }, { id: '1002' }];
}
export default async function Order({ params }) {
const { id } = await params;
return <h1>Order {id}</h1>;
}

Running next build with Next.js 16.4.6 produced:

Route (app)
┌ ○ /
├ ○ /_not-found
└ /orders/[id]
├ ● /orders/1001
└ ● /orders/1002
out/404.html
out/index.html
out/orders/1001/index.html
out/orders/1002/index.html

Pitfalls:

  • Scripts that still call next export. It no longer exists; remove it and rely on output: 'export'.
  • next/image with the default loader. It needs the optimization server; configure a custom loader or set images.unoptimized.

Hugo (v0.170.1 at the time of writing) is a single Go binary with no runtime dependencies, which makes installs simple and builds very fast, even for tens of thousands of pages. Content is Markdown with TOML, YAML or JSON front matter; templates use Go’s template language. The current quick start uses hugo new project (older releases called it hugo new site), adds a theme as a Git submodule, and serves with hugo server; hugo with no arguments builds into public/. Pages with draft = true are skipped unless you pass -D (--buildDrafts). Hugo’s quick start works with any edition; some themes require the extended edition for Sass.

Terminal window
hugo version # check the installed release
hugo new project orders-docs
cd orders-docs
git init
git submodule add https://github.com/gohugo-ananke/ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo new content content/posts/release-2-1.md # created with draft = true
hugo server -D # http://localhost:1313, drafts included
hugo # build into public/

On Windows, Hugo’s guide says to run these commands in PowerShell (not Windows PowerShell or Command Prompt) or a POSIX shell such as Git Bash; install with winget install -e --id Hugo.Hugo.Extended, choco install hugo-extended or brew install hugo on macOS.

Pitfalls:

  • Drafts missing in production. Content still marked draft = true is silently left out of the build.
  • Stale public/ files. Hugo does not empty public/ before building; delete it in CI (or use --cleanDestinationDir) so removed pages do not linger.

Jekyll (4.4.1 on RubyGems) is a Ruby static site generator built around blogs, Markdown and Liquid templates. It powered GitHub Pages’ original built-in builds, so many older project and personal sites use it. It needs Ruby 2.7 or later with development headers, RubyGems, and GCC and Make to compile native extensions. jekyll new creates a site with a Gemfile; always run Jekyll through Bundler so the site uses the gem versions it was built with. The build goes to _site/.

Terminal window
gem install jekyll bundler
jekyll new orders-blog
cd orders-blog
bundle exec jekyll serve --livereload # http://localhost:4000
bundle exec jekyll build # output in _site/

Pitfalls:

  • jekyll serve failing on Ruby 3. On Ruby 3.0 and later the serve step can fail; Jekyll’s quickstart fixes it by adding webrick with bundle add webrick.
  • Assuming GitHub Pages runs your plugins. The classic GitHub Pages build supports only an allowlisted set of plugins; build with GitHub Actions and publish _site/ to use others.

Docusaurus (3.10.2 on npm) is a React-based documentation generator from Meta with docs, blog and pages plugins, built-in versioning, internationalization and search integrations. Version 3.10 needs Node.js 20 or later. The classic template gives docs, blog and a landing page; --typescript scaffolds a TypeScript project. Note the different script names: npm run start for the dev server and npm run serve to preview the production build, which goes to build/.

Terminal window
npx create-docusaurus@latest orders-docs classic
cd orders-docs
npm run start # dev server, usually http://localhost:3000
npm run build # output in build/
npm run serve # preview build/ locally

Pitfalls:

  • Broken links fail the build. By default Docusaurus stops on broken internal links. That is useful; fix the link rather than lowering onBrokenLinks.
  • Versioning too early. Each version copies the docs folder; snapshot a version only when you actually support two releases at once.

VitePress (1.6.4 is the current release; 2.0 is in alpha) is a Vite and Vue powered generator focused on documentation. Pages are Markdown with optional Vue components, configured in .vitepress/config.mts. It renders static HTML for each page and then behaves like a single-page app for fast navigation. The 1.x docs require Node.js 18 or later. npx vitepress init asks where to put the docs (commonly ./docs) and adds the docs:dev, docs:build and docs:preview scripts; the build goes to docs/.vitepress/dist/.

Terminal window
npm add -D vitepress
npx vitepress init # choose ./docs; adds the docs:* scripts
npm run docs:dev # http://localhost:5173
npm run docs:build # output in docs/.vitepress/dist/
npm run docs:preview

Building a two-page OrdersPortal site (a layout: home page and getting-started.md) with VitePress 1.6.4 reported build complete in 3.11s. and produced 404.html, index.html, getting-started.html, an assets/ folder and hashmap.json in docs/.vitepress/dist/.

Pitfalls:

  • Clean URLs on the host. VitePress builds getting-started.html; links without .html need the host to resolve them, or set cleanUrls and confirm the host supports it.
  • Committing the cache. Add docs/.vitepress/cache and docs/.vitepress/dist to .gitignore.

MkDocs (1.6.1 on PyPI, released in August 2024) is a Python generator for project documentation: Markdown pages plus one mkdocs.yml that sets the site name, theme and navigation. mkdocs new creates that file and docs/index.md; mkdocs serve runs a live-reloading server on http://127.0.0.1:8000/; mkdocs build writes site/, and mkdocs gh-deploy publishes to GitHub Pages. MkDocs 1.6.1 supports Python 3.8 and later.

Most MkDocs sites use the Material for MkDocs theme, and its maintainers have announced that Material for MkDocs reaches end of life on May 5, 2027, with critical fixes and security updates until then. They point users to Zensical, their successor generator, which can read an existing mkdocs.yml. Factor that into a new project’s choice.

Terminal window
python3 -m venv .venv && . .venv/bin/activate
pip install mkdocs
mkdocs new orders-docs
cd orders-docs
mkdocs serve # http://127.0.0.1:8000/
mkdocs build # output in site/

Running mkdocs new and mkdocs build with MkDocs 1.6.1 printed:

INFO - Creating project directory: orders-docs
INFO - Writing config file: orders-docs/mkdocs.yml
INFO - Writing initial docs: orders-docs/docs/index.md
INFO - Cleaning site directory
INFO - Building documentation to directory: .../orders-docs/site
INFO - Documentation built in 0.05 seconds

The site/ folder then held index.html, 404.html, sitemap.xml, the theme’s css/, js/ and webfonts/, and a search/ index.

Pitfalls:

  • Installing into the system Python. Use a virtual environment (or pipx/uv) so theme and plugin versions are pinned per project.
  • Committing site/. It is build output; add it to .gitignore and build in CI.

Gatsby (5.16.1 on npm) is a React framework that pulls data from Markdown, CMSs and APIs into a GraphQL layer at build time and renders static pages. npm init gatsby runs an interactive setup; npm run develop serves on port 8000; npm run build writes public/; and npm run serve previews it. The gatsby 5.16.1 package declares support for Node.js 18 up to, but not including, 26, and releases have slowed: 5.16.1 (February 2026) is the most recent at the time of writing.

Terminal window
npm init gatsby # interactive: name, CMS, styling, plugins
cd my-gatsby-site
npm run develop # http://localhost:8000
npm run build # output in public/
npm run serve # preview the build

Pitfalls:

  • Node.js 26. The engines range excludes it; pin Node.js 24 LTS for Gatsby projects.
  • Choosing it for a new site. Given the slower release pace, compare it with Astro or Next.js static export before starting something new; existing Gatsby sites are fine to maintain.
If you need Consider
A content site that may later need some interactivity or server routes Astro
A React application that can be prerendered entirely Next.js static export
Thousands of pages and the fastest builds, no Node.js Hugo
Versioned product docs with a React ecosystem Docusaurus
Lightweight docs in a Vue or Vite project VitePress
Docs written by a Python team, close to the code MkDocs (note the Material theme end of life) or Zensical
An existing blog on GitHub Pages Jekyll

The output of all of them is a folder; hosting, custom domains and certificates are the same problem whichever you choose, covered in website hosting.

What actually gets deployed for a static site? Only the build output folder (dist/, out/, public/, _site/, build/ or site/): HTML, CSS, JavaScript and assets. No application server runs, which is why static sites are cheap, fast from a CDN and have a small attack surface.

How does Next.js static export differ from a normal Next.js deployment? output: 'export' runs everything at build time and writes HTML to out/. Anything that needs a request (cookies, rewrites, ISR, Server Actions, Proxy, default image optimization) is unsupported, and dynamic routes must be enumerated with generateStaticParams().

Why run Jekyll with bundle exec? It runs Jekyll with the exact gem versions in the project’s Gemfile.lock instead of whatever is installed globally, so builds are reproducible across machines and CI.

What breaks when you deploy a generator’s output to a subpath? Absolute links and asset URLs that assume the site is at /. Each generator has a setting for it (base in Astro and VitePress, baseURL in Hugo, baseurl in Jekyll, baseUrl in Docusaurus, basePath in Next.js, site_url in MkDocs), and links in your own templates must use it.

Senior scenario: OrdersPortal’s docs are on MkDocs with Material, and the theme reaches end of life in May 2027. What do you do? Inventory what the site depends on: Material features, third-party plugins, custom templates and the deployment pipeline. Build the current mkdocs.yml with Zensical on a branch and diff the output (navigation, search, redirects, link check) to measure the gap, and in parallel prototype the docs in one alternative (Astro with Starlight, Docusaurus or VitePress) if plugin coverage is poor. Decide well before May 2027 with a migration plan that preserves URLs with redirects, then freeze theme and plugin versions on the old stack until the cutover.