gatsby-theme-kb

A Gatsby theme for publishing Knowledge Base.

See the demo and documentation.

Setup in your Gatsby project

  1. Install dependency
yarn add gatsby-theme-kb
  1. Add these to your gatsby-config.js file:
module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-kb`,
      options: {
        contentPath: path.resolve(__dirname, 'content'),
        rootNote: 'readme',
        wikiLinkLabelTemplate: '[[{{ refWord }}]]',
        getPluginMdx(defaultPluginMdx) {
          // customise pre-configured `gatsby-plugin-mdx`, for example:
          // defaultPluginMdx.options.gatsbyRemarkPlugins.push({
          //   resolve: 'gatsby-remark-prismjs',
          // })
          return defaultPluginMdx
        },
      },
    },
  ],
};
  1. Add notes to your site by adding md or mdx files in content directory, especially you need a content/readme.md file if you are using above configs.
  2. Start developing your site by running gatsby develop. If you are using above configuration, your start url will be ’http://localhost:8000’.

Usage

Options

Key Default value Description
rootNote /readme Root note’s name (without exts)
contentPath Location of local content
extensions [‘.md’, ‘.mdx’] Valid content file exts
ignore ['.git'] A list of file globs to ignore
wikiLinkLabelTemplate A template string for specifying wiki link label, see options.wikiLinkLabelTemplate
getPluginMdx (defaultPluginMdx) => PluginMdx Customise pre-configured gatsby-plugin-mdx, please do always return a valid gatsby plugin object

options.wikiLinkLabelTemplate

When a wikilink is resolved and rendered as an anchor element, the anchor label is by default [[reference-word]]. But some people may prefer some other forms, so here is one option for specifying the link label you want.

The template string will be processed in a mustache alike manner, the variable inside {{}} will be replaced by real value. Currently there are some variables available:

  • refWord, the reference word inside the double brackets, usually it’s the filename (without exts).
  • title, the title of the page, may be the frontmatter title field value, or h1 of the markdown content.

For example there is page A, filename is page-a.md, page title is Awesome Themes.

And in page B I write the reference as [[page-a]].

  • config wikiLinkLabelTemplate: '[[ {{refWord}} ]]', will generate [[ page-a ]] as link label.
  • config wikiLinkLabelTemplate: '{{title}}', will generate Awesome Themes as link label.