gatsby-theme-documentation

A minimalist Gatsby Theme for documentation sites built with MDX and Theme UI.

Get up and running in seconds with a beautiful docs site so you can do what's more important: write docs.

Features

📑 MDX files for JSX in Markdown
🎨 Theme UI-based theming
💻 Syntax highlighting
📰 MDX-based sidebar navigation
🛣 Automatic readme routing
🧩 Shortcode support with React components
🍔 Collapsible menu
📱 Mobile friendly
🎣 Custom docs schema

Installation

yarn add gatsby-theme-documentation

Install as a starter

Name	Command
Base	`gatsby new johno/gatsby-starter-documentation`
Dark	`gatsby new johno/gatsby-starter-documentation-dark`
Tomato	`gatsby new johno/gatsby-starter-documentation-tomato`

Read the full setup guide

Usage

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-theme-documentation'
  ]
}

Customizing the sidebar

gatsby-theme-documentation uses a sidebar.mdx file to populate the navigation. In order to customize it you can shadow it by creating a file at src/gatsby-theme-documentation/sidebar.mdx.

Example `sidebar.mdx`

- [Introduction](/introduction/)
- [Getting Started](/getting-started/)
- [GitHub](https://github.com/johno/gatsby-theme-documentation)

Customizing the header

Similarly to sidebar customization, you can also change the header content by writing MDX. You can shadow the default header by creating a file at src/gatsby-theme-documentation/header.mdx

Example `header.mdx`

# ![Docs Logo](https://contrast.now.sh/white/black?width=80&height=40&text=DOCS)

- [GitHub](https://github.com/johno/gatsby-theme-documentation)
- [Twitter](https://twitter.com/4lpine)

Adding component shortcodes

You can add shortcodes to your docs site which can be used throughout your docs pages by extending the components passed to MDXProvider. You can do this by using component shadowing and creating the following file in the root of your project: src/gatsby-theme-documentation/components.js.

Example `components.js`

import baseComponents from 'gatsby-theme-documentation/src/components'

import MyCustomH1 from '../components/my-custom-h1'

export default {
  ...baseComponents,
  h1: MyCustomH1
}

Readme routing

In order to get documents rendered in directories on GitHub, it's common to specify a readme.md similarly to the index.html on normal websites. Since this theme is meant to work seamlessly with docs directories on GitHub, file/path/readme.md will be automatically turned into /file/path/index.html in the built site. Links will also be redirected to support the new url scheme.

Docs schema

This theme creates a Docs type which can be queried as an individual document or a collection. This data can be used to create additional pages, create summaries, etc.

Query an individual document

{
  docs(slug: {eq: "/some-page"}) {
    slug
    body
  }
}

Query a collection

{
  allDocs {
    slug
  }
}

Using pathPrefix creates wrong hyperlinks in sidebar

Steps to reproduce

Add pathPrefix config to gatsby-config.js
Build using gatsby build --prefix-paths (Gatsby docs)

Expected behavior

Paths should have the path prefix added once.
e.g. /endpoints would become /my-path/endpoints after build.

Actual behavior

For assets and links inside .mdx pages inside /docs the path is added once, but for links created in sidebar.mdx the path is added twice.
Actual result: /my-path/my-path/endpoints

Actual generated example

src/gatsby-theme-documentation/sidebar.mdx

<li><div class="css-70qvj9">
<a class="css-1dbh7qa" href="/my-path/my-path/">Api</a>
</div></li>
<li><div class="css-70qvj9">
<a class="css-1dbh7qa" href="/my-path/my-path/installation">Installation</a>
</div></li>
<li><div class="css-70qvj9"><a class="css-1dbh7qa" href="/my-path/my-path/endpoints">Endpoints</a>
</div></li>

`gatsby-config.js`

module.exports = {
	siteMetadata: {
		title: 'API Documentation',
		description: 'Docs for API',
	},
	plugins: [
		'gatsby-theme-documentation',
	],
	pathPrefix: 'my-path',
}

johno / gatsby-theme-documentation Goto Github PK