Gatsby Starter Blog Musts

Mon Feb 25 2019

Code syntax highlighting
- Not so easy way
- Gatsby's official solution
Header ID's for links: Table of contents enabler

Code syntax highlighting

When installing the great gatsby-starter-blog you may notice that your code blocks are not getting highlighted at all. Let's solve this.

Not so easy way (actually not working for me)

We love Github syntax highlighting, but there isn't any simple and reliable solution to get that exact kind of beautiful Github look directly from a gatsby plugin. There are non gatsby options: an honorable mention is Github markdown, which apparently does that. I wasn't able to get colors. It goes like this:

npm install it
import "github-markdown-css/github-markdown.css" it in gatsby-browser.js

manually add markdown-body class somewhere in your layout

// src/components/Layout.js
import React from "react"
//...
class Layout extends React.Component {
    render() {
      return (
        <div>
          <header>{header}</header>
          // --------- like below -------------
          <main class={[
            `markdown-body`
          ]}>
          // --------- like above -------------
            {children}
          </main>
          <footer>
            © {new Date().getFullYear()}, Built with
            {` `}
            <a href="https://www.gatsbyjs.org">Gatsby</a>
          </footer>
        </div>
      )
    }
}
export default Layout

This isn't a one step configuration. There are styling conflicts with gatsby-starter-blog's default css. Getting colors working, was an additional trouble (at which point I started looking for standard solutions).

Altering the `<head>` and `<body>` tags

The thing with Gatsby is that you are not supposed to alter .cache/default-html.js, which contains the main <head> and <body> tags. If you really need to, you can make a copy of the default-html.js file to your src/. Otherwise you can also use Helmet to alter these root tags by inserting <Helmet></Helmet> tags into your JSX components.

If you really need customization, try the solutions above, otherwise, just sticking to the official solution will save you time and headaches.

Gatsby's official solution

You probably still want code syntax highlighting, and luckily Gatsby has you covered.

Steps are outlined here

npm install prismjs,
npm install --save gatsby-transformer-remark gatsby-remark-prismjs
include a handle of the gatsby plugin in your gatsby-config.js file, under gatsby-transformer-remark plugin options > plugins
add the options
import "prismjs/themes/prism.css" or some theme that fits your needs, see in prismjs' folder for options, and preview them on their website (themes are on the left as a column of discs, it took a few seconds to figure out).
done

Gatsby's plugin will automagically handle the rest for you.

Header ID's for links: Table of contents enabler

Have you seen the table of contents at the beginning? If you like it, then this is for you.

When writing long markdown documents, you may need to have a table of contents in order to facilitate navigation. Moreover, adding a link snippet to each of the headers makes your document easily referable by sections. Gatsby has a plugin for this, but it is not enabled by default. gatsby-remark-autolink-headers (github repo) does header linking and linkable ids. Getting it to work is pretty simple: