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.
Topics on this page
Section titled “Topics on this page”| 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.
npm create astro@latest orders-docscd orders-docsnpm run dev # http://localhost:4321npm run build # static output in dist/npm run preview # serve dist/ locallyThe 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, setsiteandbaseor every asset path breaks.
Next static export
Section titled “Next static export”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.
/** @type {import('next').NextConfig} */const nextConfig = { output: 'export', trailingSlash: true, // /orders/1001/ -> out/orders/1001/index.html};export default nextConfig;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.htmlout/index.htmlout/orders/1001/index.htmlout/orders/1002/index.htmlPitfalls:
- Scripts that still call
next export. It no longer exists; remove it and rely onoutput: 'export'. next/imagewith the default loader. It needs the optimization server; configure a custom loader or setimages.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.
hugo version # check the installed releasehugo new project orders-docscd orders-docsgit initgit submodule add https://github.com/gohugo-ananke/ananke themes/anankeecho "theme = 'ananke'" >> hugo.tomlhugo new content content/posts/release-2-1.md # created with draft = truehugo server -D # http://localhost:1313, drafts includedhugo # 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 = trueis silently left out of the build. - Stale
public/files. Hugo does not emptypublic/before building; delete it in CI (or use--cleanDestinationDir) so removed pages do not linger.
Jekyll
Section titled “Jekyll”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/.
gem install jekyll bundlerjekyll new orders-blogcd orders-blogbundle exec jekyll serve --livereload # http://localhost:4000bundle exec jekyll build # output in _site/Pitfalls:
jekyll servefailing on Ruby 3. On Ruby 3.0 and later the serve step can fail; Jekyll’s quickstart fixes it by addingwebrickwithbundle 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
Section titled “Docusaurus”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/.
npx create-docusaurus@latest orders-docs classiccd orders-docsnpm run start # dev server, usually http://localhost:3000npm run build # output in build/npm run serve # preview build/ locallyPitfalls:
- 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
Section titled “VitePress”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/.
npm add -D vitepressnpx vitepress init # choose ./docs; adds the docs:* scriptsnpm run docs:dev # http://localhost:5173npm run docs:build # output in docs/.vitepress/dist/npm run docs:previewBuilding 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.htmlneed the host to resolve them, or setcleanUrlsand confirm the host supports it. - Committing the cache. Add
docs/.vitepress/cacheanddocs/.vitepress/distto.gitignore.
MkDocs
Section titled “MkDocs”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.
python3 -m venv .venv && . .venv/bin/activatepip install mkdocsmkdocs new orders-docscd orders-docsmkdocs 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-docsINFO - Writing config file: orders-docs/mkdocs.ymlINFO - Writing initial docs: orders-docs/docs/index.mdINFO - Cleaning site directoryINFO - Building documentation to directory: .../orders-docs/siteINFO - Documentation built in 0.05 secondsThe 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.gitignoreand build in CI.
Gatsby
Section titled “Gatsby”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.
npm init gatsby # interactive: name, CMS, styling, pluginscd my-gatsby-sitenpm run develop # http://localhost:8000npm run build # output in public/npm run serve # preview the buildPitfalls:
- Node.js 26. The
enginesrange 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.
Choosing between them
Section titled “Choosing between them”| 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.
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Static websites overview: when to choose static, workflow, hosting and pipelines.
- Astro introduction and Astro integrations, build and deploy
- Website hosting: custom domains and certificates.