gatsby-starter-blog: a Markdown blog starter built on Gatsby 5

The problem gatsby-starter-blog removes, and for whom

Starting a blog usually means deciding on a static site generator, wiring Markdown parsing, image handling, an RSS feed, a web manifest, syntax highlighting and a build step before you write a single post. gatsby-starter-blog is the official Gatsby answer to that setup work. It is a repository you clone rather than a package you install, and its package.json describes it as "A starter for a blog powered by Gatsby and Markdown".

The intended user is a React developer who already knows components and is willing to learn GraphQL. The starter's own README points readers at the Gatsby tutorial for that reason, and the develop server exposes a second URL, http://localhost:8000/___graphql, for exploring the data layer. If you have never written a GraphQL query, the first hour with this repository is spent on that, not on your blog.

It is a poor fit for someone who wants a writing tool. There is no admin interface, no draft workflow and no database. Posts are files on disk. The README does not document any editorial tooling, because there is none.

How the Markdown-to-page pipeline actually works

The starter is a thin layer over Gatsby's build. Files under content/ are read by gatsby-source-filesystem, parsed by gatsby-transformer-remark, and exposed as GraphQL nodes that page components query at build time. gatsby-node.js is where the starter turns those nodes into URLs, using the Gatsby Node APIs the README describes as the place for customising the build process.

Two configuration files carry most of the behaviour. gatsby-config.js holds site metadata and the plugin list; gatsby-browser.js and gatsby-ssr.js are the browser and server-rendering extension points. Images go through gatsby-plugin-image, gatsby-plugin-sharp and gatsby-transformer-sharp, while gatsby-remark-images handles images referenced inside Markdown and gatsby-remark-prismjs handles code blocks. The feed plugin generates RSS, and the manifest plugin produces the web app manifest.

The consequence of this design is that content and presentation are separated by a query boundary. Changing a layout means editing a component in src/; changing what data a page can see means editing a GraphQL query. There is no runtime content API. Everything is resolved when you run the build.

Installing gatsby-starter-blog and publishing a first post

The README's quick start uses the Gatsby CLI to scaffold a new site from the starter repository. The CLI itself has separate install instructions linked from the README, so install it first if you do not have it.

# create a new Gatsby site using the blog starter
gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

This creates a my-blog-starter directory with the starter's files. Move into it and start the development server.

cd my-blog-starter/
gatsby develop

The README states the site is then running at http://localhost:8000, with a second link at http://localhost:8000/___graphql for experimenting with queries. Editing src/pages/index.js and saving triggers a browser update in real time.

The package.json scripts give the same entry points under npm, plus the production path.

npm run develop   # gatsby develop
npm run build     # gatsby build
npm run serve     # gatsby serve, after a build
npm run clean     # gatsby clean

To add a post, create a Markdown file under content/ following the frontmatter shape of the existing files, then restart or let the develop server pick it up. The README does not spell out the frontmatter fields; read the sample posts that ship in the repository instead. `npm run format` runs Prettier across js, jsx, ts, tsx, json and md files, which is the only code-quality script present. The test script is a stub that prints "Write tests!" and exits with a non-zero status.

Where the starter stops short

The most concrete limitation is the test script. In package.json it is literally `echo "Write tests! -> https://gatsby.dev/unit-testing" && exit 1`. Any CI pipeline that runs `npm test` fails by default until you replace that line. That is a deliberate placeholder, not a bug, but it means the repository gives you no test scaffolding at all.

The README also does not document rollback, migration between Gatsby major versions, or how to move off the starter once you have customised it. There is no upgrade guide in the repository, and the repository has no published releases, so version-to-version change notes are not available here. The dependencies pin Gatsby at ^5.14.6 with React 18, and the plugin versions move in lockstep with Gatsby's own release cadence; you inherit that coupling.

Finally, the starter is opinionated about content source. It reads local files. If your writers need a hosted CMS, or you need previews for non-technical editors, you are adding a source plugin and reworking queries before the starter earns its keep. The README's pointer to community starters is the honest signal here: for many non-Markdown setups, this repository is the wrong starting point.

gatsby-starter-blog against a Next.js Markdown blog

The closest alternative for a React developer is a Next.js blog scaffold, and the difference is architectural rather than cosmetic. Next.js resolves routes through the file system and lets you fetch data inside page components at request or build time; there is no separate schema layer to learn. Gatsby, and therefore this starter, puts a GraphQL data layer between your files and your components. That layer is what makes the starter's plugin ecosystem work: swap gatsby-source-filesystem for a CMS source plugin and your page queries stay roughly the same shape.

The trade-off runs the other way too. With Next.js you write the Markdown parsing, image optimisation and feed generation yourself or pick libraries individually. gatsby-starter-blog ships those decisions already made, at the cost of adopting Gatsby's plugin versions and build model. If you value a schema you can query from any component over a smaller dependency surface, the starter is the better fit. If you want the fewest moving parts and no GraphQL, it is not.

Licence, maintenance and upgrade cost

The repository is licensed under 0BSD, and the README is explicit about how to treat it: the LICENSE file is described as a placeholder you can replace with your own. That is a permissive licence with no attribution requirement, which makes it easy to reuse the scaffold in a commercial site. It does not resolve the licences of the dependencies you pull in through package.json, and no legal advice follows from that observation.

On maintenance, the last push to the repository was on 2026-05-11. The repository is not archived. The dependency list is the real upgrade surface: gatsby, five gatsby-plugin-* packages, three gatsby-remark-* packages, three gatsby-transformer-* packages, prismjs, react and react-dom. Gatsby's own major releases drive those versions, so an upgrade is a coordinated bump rather than a single package update. Budget for reading the Gatsby changelog before each major, and keep `npm run clean` in mind when builds behave oddly after an upgrade, since stale caches are the usual first suspect.

Editorial conclusion

Adopt gatsby-starter-blog if you want a Markdown blog whose data layer you control and you are comfortable owning a Gatsby 5 dependency tree; skip it if you want a hosted editor, comments or analytics out of the box, because the starter ships none of those. Before committing, run npm run build and npm run serve to confirm the production output, and read the LICENSE file, which the README describes as a placeholder you are expected to replace with your own.

Frequently asked questions

Official sources

1. gatsbyjs/gatsby-starter-blog on GitHub
2. Issues
3. License: 0BSD
4. Project website
5. README