Usubeni is a Gatsby.js v5 blog theme that turns Markdown posts into a fast, SEO-optimized static blog with built-in code highlighting, LaTeX rendering, and a table of contents.
What is Usubeni?
Usubeni is an open-source blog theme built on Gatsby.js v5 by developer ssshooter, available on GitHub at ssshooter/gatsby-theme-usubeni. It takes Markdown files that you place in the pages folder (each with optional YAML front matter) and produces a static multi-page site, which the author demonstrates at ssshooter.com/tag/coding/. The project is a forkable starter rather than a publishable npm theme, so you clone the repository, edit configuration files, and deploy the generated site to any static host. A Gatsby v4 version is also available on the V4 branch.
Key Features
- Lighthouse performance score of 90 — the theme is optimized for speed out of the box.
- Gatsby v5 with up-to-date dependencies — most Gatsby-related packages are kept current.
- Integrated code highlighting — syntax highlighting via
prismjs. - Integrated LaTeX — math typesetting via
katex. - Configured
.npmrc— eases the pain of installing dependencies on some platforms. - Built-in Table of Contents — auto-generated TOC for posts.
- Built-in image and tag libraries — organize media and classify posts by tags.
- SEO optimization — includes meta tags and structured output.
- Comment component — a ready-to-use comment rendering and publishing component, though the backend is not open source.
Who is it for?
- Bloggers who want a modern, static, fast blog without a server and who are willing to learn Gatsby's conventions.
- Developers who enjoy GraphQL and want a customizable starting point for a personal site.
- Experienced Gatsby users who want to integrate their own comment system by replacing the included component.
What can you do with Usubeni?
- Indie bloggers: write Markdown posts and generate a static blog with built-in TOC, code highlighting, and tag archives at
/tag/xxx/. - Theme customizers: change the color variables in
src/css/global.scssand editsrc/settings.jsto personalize the site. - Self-hosters: deploy to free services like Vercel, Netlify, or Gatsby Cloud with one-click buttons or continuous deployment.
How does Usubeni work?
Start by forking or cloning the repository, then install dependencies with yarn (recommended). Modify gatsby-config.js and src/settings.js with your site info. Add new articles in the pages folder or use the built-in scripts: node createPost.js -t title -d 2023-11-18 -f (the -d flag is optional; -f creates just a Markdown file instead of a folder). Run npm start for local development and npm run build for a production build. Deploy the output to any static hosting service.
Pros and cons
- Pros: Fast by default, high Lighthouse score, integrates prismjs and katex, includes TOC and SEO.
- Cons: Steeper learning curve than Hexo, around 500 MB of dependencies, PWA is not enabled by default and may cause issues with pre-rendering.
FAQ
Does Usubeni support PWA?
No, PWA is not enabled by default. The author notes that enabling PWA with gatsby-plugin-manifest and gatsby-plugin-offline may conflict with pre-rendered multi-page output, making pre-rendered pages less useful. You can still add PWA manually if you accept that trade-off.
How do I create a new blog post?
Use the command node createPost.js -t title -d 2023-11-18 -f. The -d option sets the date and is optional; -f creates only a Markdown file. The post goes into the pages folder with the front matter fields slug, date, title, tags, description, released, and hidden.
Is Usubeni free to use?
Yes, it is released as an open-source theme on GitHub. You can fork it, modify it, and use it for your own blog without any license fee.
What comment systems can I use?
The theme ships with a comment component (src/components/Comment.js) but the backend is not open source. The author suggests integrating Staticman, valine, waline, twikoo, or Disqus instead.
How do I change the theme colors?
Open src/css/global.scss and modify the color variables at the top. This is the simplest way to make the theme feel your own. The author also welcomes PRs with attractive color schemes.
