Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/johno/gatsby-theme-documentation
A minimalist Gatsby Theme for documentation sites built with MDX and Theme UI
https://github.com/johno/gatsby-theme-documentation
Last synced: 3 months ago
JSON representation
A minimalist Gatsby Theme for documentation sites built with MDX and Theme UI
- Host: GitHub
- URL: https://github.com/johno/gatsby-theme-documentation
- Owner: johno
- License: mit
- Created: 2019-07-07T22:58:02.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-26T12:47:23.000Z (over 1 year ago)
- Last Synced: 2024-04-14T07:47:47.784Z (3 months ago)
- Language: JavaScript
- Homepage: https://docs-theme.johno.com
- Size: 6.5 MB
- Stars: 133
- Watchers: 3
- Forks: 18
- Open Issues: 41
-
Metadata Files:
- Readme: readme.md
- License: license.md
Lists
- awesome-gatsby - Documentation
- awesome-gatsby - Documentation
README
# gatsby-theme-documentation
A minimalist [Gatsby Theme](https://gatsbyjs.org/docs/themes)
for documentation sites built with [MDX](https://mdxjs.com)
and [Theme UI](https://theme-ui.com).
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](#customizing-the-sidebar)
- 🛣 [Automatic readme routing](#readme-routing)
- 🧩 [Shortcode support with React components](#shortcodes)
- 🍔 Collapsible menu
- 📱 Mobile friendly
- 🎣 [Custom docs schema](#docs-schema)
## Installation
```
yarn add gatsby-theme-documentation
```
### Install as a starter
Name | Command
---- | -------
[Base](https://github.com/johno/gatsby-starter-documentation) | `gatsby new johno/gatsby-starter-documentation`
[Dark](https://github.com/johno/gatsby-starter-documentation-dark) | `gatsby new johno/gatsby-starter-documentation-dark`
[Tomato](https://github.com/johno/gatsby-starter-documentation-tomato) | `gatsby new johno/gatsby-starter-documentation-tomato`
[Read the full setup guide](https://johno.com/creating-a-minimalist-docs-site-with-gatsby-and-mdx)
## Usage
```js
// 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`
```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`
```mdx
# 
- [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`
```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
```graphql
{
docs(slug: {eq: "/some-page"}) {
slug
body
}
}
```
#### Query a collection
```graphql
{
allDocs {
slug
}
}
```