@readysteady/gatsby-theme-docs v0.1.2

A Gatsby theme for creating a documentation site.

Features

• Markdown documentation for your site sourced from a documentation folder.
• Light / Dark mode.
• PrismJS code highlighting.
• MermaidJS diagrams.
• MDX for super extensible documentation.
• Customization using Theme-UI by shadowing the theme.js file.
• Configurable navigation menu using simple YAML format.
• New DocPost node interface that allows other sources for documentation (advanced useage).

Installation

Create a new Gatsby site and add theme to your project

npm install --save @readysteady/gatsby-theme-docs

Usage

Add the theme as a plugin in your gatsby-config.js file.

module.exports = {
    plugins: [`@readysteady/gatsby-theme-docs`],
}

Or to use options...

module.exports = {
    plugins: [
        {
            resolve: `@readysteady/gatsby-theme-docs`,
            options: {
                contentPath: 'docs',
                basePath: '/',
            },
        },
    ],
}

Theme options

Additional configuration

In addition to the theme options, you can configure some options via the siteMetadata object in your site's gatsby-config.js

// gatsby-config.js
module.exports = {
    siteMetadata: {
        // Your documentation site title
        title: `My Documentation Site`,
        // Text in the site footer
        footer: `Copyright(C) 2019 My Company`
    },
}

Documentation Folder

Sample site out of the box

If no documentation folder is found a new folder will be created with some example documentation.

If no navigation.yaml file is found an example one will be created within your documentation folder.

Document Format

Documents are created using markdown and requires some markdown frontmatter. The front matter currently supported are:

Example Document

---
title: "A very important document"
---

Nullam id dolor id nibh ultricies vehicula ut id elit.
Vestibulum id ligula porta felis euismod semper.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Etiam porta sem malesuada magna mollis euismod. Maecenas faucibus mollis interdum.

Navigation

To configure the navigation menu for your site you will need to crate a navigation.yaml file in the same folder as your markdown documents (default: docs)

The YAML file allows you to define the structure of your navigation.

Example

# Navigation supports up to 4 levels of nesting.
# This file is an example.
# Title will be ignored, but keep it here.
- title: Docs
  # `key` has to be `docSidebar` for navigation to work.
  key: docSidebar
  items:
    # Level 0
    - title: Introduction
      link: /
    # Level 0
    - title: Expandable
      link: /expandable/
      items:
        # Level 1
        - title: Level One
          link: /level-1/
          items:
            # Level 2
            - title: Level Two
              link: /level-2/
            - title: Also Level Two
              link: /also-level-2/
              items:
                # Level 3
                - title: Level Three
                  link: /level-3/
    # Level 0
    - title: The End.
      link: /end/