Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


MIT license npm version


  • MDX
  • Chakra UI theming
  • Light mode / Dark mode
  • Code highlighting with Shiki
  • Tags
  • Related posts based on simple tag matching
  • Psagination
  • Social buttons (GitHub, Twitter, RSS)



For a new site

You can use @zzzkan/gatsby-starter-blog.

npx gatsby new gatsby-starter-blog https://github.com/zzzkan/gatsby-starter-blog

For an existing site

Install the blog theme

npm install @zzzkan/gatsby-theme-blog

and then add the configuration to your gatsby-config.js

// gatsby-config.js
module.exports = {
  plugins: [
      resolve: "@zzzkan/gatsby-theme-blog",
      options: {
        // options


Theme options

Available theme options are:

Key Default value Description
lang en lang global attribute
basePath / Root url for all blog posts
contentPath content/posts Location of blog posts
postImageMaxWidth 960 Max width of images in your blog posts
featuredImageAspectRatio 1.7777 Aspect ratio of featured images
dateFormatString YYYY-MM-DD Date format
postsLimit 30 Max number of posts per page
relatedPostsLimit 6 Max number of posts in related posts
shikiTheme dracula Shiki theme
links [] Links to your external sites

A example is shown below.

// gatsby-config.js
module.exports = {
  plugins: [
      resolve: "@zzzkan/gatsby-theme-blog",
      options: {
        lang: "en",
        basePath: "/blog",
        contentPath: "contents/entries",
        postImageMaxWidth: 1380,
        featuredImageAspectRatio: 2,
        dateFormatString: "MMMM DD, YYYY",
        postsLimit: 10,
        relatedPostsLimit: 6,
        shikiTheme: "dracula",
        links: [
            name: "GitHub",
            url: "https://github.com/zzzkan",
            name: "Twitter",
            url: "https://twitter.com/_zzzkan",

Site metadata

There are items that you can customize via the siteMetadata object in gatsby-config.js. These are used for headers, footers, SEO, etc.

Key Description
title Blog title
siteUrl Blog site url
description Blog description
author Author
author Author url
publicationYear Blog publication year
imageUrl Image url for default og:image

A example is shown below.

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: "zzzkan blog",
    siteUrl: "https://zzzkan-gatsby-theme-blog.netlify.app/",
    description: "gatsby-theme-blog by @zzzkan.",
    author: "zzzkan",
    authorUrl: "https://zzzkan.me/",
    publicationYear: 2023,
    imageUrl: "https://zzzkan-gatsby-theme-blog.netlify.app/banner.png",

Chakra UI theme

This blog theme is based on Chakra UI. You can easily change the site color scheme, or other styles by shadowing Chakra UI theme.

A example is shown below.

// /src/@zzzkan/gatsby-theme-blog/theme/colors.ts
const colors = {
  tint: { default: "#350697", _dark: "#E0BBFE" },
  primaryText: { default: "#4A4850", _dark: "#FBFAFC" },
  secondaryText: { default: "#9995A3", _dark: "#D0CBD8" },
  onTintText: { default: "white", _dark: "#232226" },
  primaryBackground: { default: "white", _dark: "#232226" },
  secondaryBackground: {
    default: "RGBA(0, 0, 0, 0.02)",
    _dark: "RGBA(255, 255, 255, 0.02)",
  highlightCode: {
    default: "RGBA(255, 255, 255, 0.05)",

export default colors

Adding content


New blog posts can be created by adding MDX files in contentPath, and add the frontmatter.


You can set up blog post metadata in frontmatter.

Key Description
slug (optional) Custom slug (default : file path on the file system)
title Title
publishedDate Published date
updatedDate (optional) Updated date
featuredImage (optional) Featured image
featuredImageAlt (optional) Featured image alternative
featuredImageCreditText (optional) Featured image credit text
featuredImageCreditLink (optional) Featured image credit link
tags (optional) Tags
description (optional) Description
draft (optional) If draft, set to true
noindex (optional) If blocking search index, set to true

A example is shown below.

slug: ipsum-consetetur
title: Ipsum consetetur nulla facilisi eos
publishedDate: 2022-10-01
updatedDate: 2022-10-02
featuredImage: "./jane-almon-7rriIaBH6JY-unsplash.jpg"
featuredImageAlt: "A white pitbull wearing big googly-eye glasses"
featuredImageCreditText: "Jane Almon"
featuredImageCreditLink: "https://unsplash.com/photos/7rriIaBH6JY"
  - sample
  - ipsum
  - consetetur
  - nulla
description: Ipsum consetetur nulla facilisi eos
draft: true
noindex: true

Code highlighting

This blog theme uses Shiki for code highlighting. It also supports highlight lines and showing line numbers by metastrings.

A example is shown below.

```jsx {1,5} showLineNumbers
import { useFloating } from "@floating-ui/react-dom"
function MyComponent() {
  const { x, y, reference, floating } = useFloating()
  return (
      <div ref={reference} />
      <div ref={floating} />

Inline codes can also be highlighted.

justo autem `import { useFloating } from "@floating-ui/react-dom"{:jsx}` amet justo kasd nonumy.


New pages can be created by adding files to /src/pages. You can import @zzzkan/gatsby-theme-blog/src/components/Layout if you want to apply the same layout as the theme.

A example is shown below.

// /src/pages/index.tsx
import React from "react"
import { Heading } from "@chakra-ui/react"
import { Layout } from "@zzzkan/gatsby-theme-blog/src/components/Layout"

const Home: React.FC = () => {
  return (
      <Heading as={"h1"} marginBottom={3}>

export default Home


“Shadowing” will be useful if you want to customize the theme. For more information, please read the guide Shadowing in Gatsby Themes.

Contact me

Thanks for your interest in my project. Don’t hesitate to contact me via Twitter if you need anything.

© 2023 Gatsby, Inc.