Deploy a best practice and fully customizable documentation site with platformOS DocsKit.
Inspired by our multi-award winning documentation site, our documentation package will provide everything you need to build best practice documentation sites for your projects.
## Installation
```sh
npm install @platformos/gatsby-theme-platformos-docskit
```
## Usage
### Theme options
| Key | Default Value | Description |
| -------------------- | --------------- | -----------------------------------------------------------------------------------------------------------------------------------|
| `useLegacyUrls` | `false` | When this flag is set to `true` it appends `index.html` to the page urls and internal links |
| `showFullNavigation` | `false` | When set to `true` it shows the full navigation tree on every page, otherwise it filters it down to the current topic |
| `basePath` | `""` | If there is a pathPrefix then it should be passed to the plugin as well as `basePath`. Used by `pos-fix-remark-path-prefix-plugin` |
| `remarkImageOptions` | `{}` | Custom options passed to `gatsby-remark-images`, optional. See https://www.gatsbyjs.com/plugins/gatsby-remark-images/#options |
#### Example config
```js
plugins: [
{
resolve: '@platformos/gatsby-theme-platformos-docskit',
options: {
showFullNavigation: true,
gatsbyRemarkOptions: {
withWebp: true,
withAvif: true
}
}
}
]
```
### Sources
The DocsKit theme uses `/docs` as the source folder for your MD(X) documentation files and `/partials` for shared reusable mdx snippets.
### Navigation
The theme automatically generates the navigation tree based on your folder structure or your page slugs.
The main navigation shows the top-level pages and the sidebar navigation shows the navigation tree filtered down to the current second-level page (topic). You can override this behavior using the `showFullNavigation` theme config.
The order of the navigation items is based on the filename of your source files, so you can use prefixes in your mdx files: `/docs/01-this-comes-first.mdx`, `/docs/02-this-comes-next.mdx`, etc.
There is an automatically generated table-of-contents (on-page navigation) for every page that has h2/h3 headings.
You can hide the sidebar navigation and the ToC by adding `hideNavigation: true` and `hideToc: true` to the frontmatter of your MDX page.
### Features
The theme comes preconfigured with the following plugins:
* gatsby-plugin-image
* gatsby-plugin-mdx
* gatsby-remark-images
* gatsby-remark-autolink-headers
* gatsby-remark-embed-video
* gatsby-remark-responsive-iframe
* gatsby-remark-external-links
* gatsby-remark-prismjs
* gatsby-plugin-sharp
* gatsby-transformer-sharp
It also provides some default components that you can use in your MDX documentation files and can be enhanced with shadowing:
``, ``, ``, ``
### Theming
You can update the color scheme of the site by providing a theme configuration file.
For the default theme configuration see: `/src/theme/colors.js`
### Shadowing
Please read the guide [Shadowing in Gatsby Themes](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/shadowing/) to understand how shadowing works.
