npm package: @platformos/gatsby-theme-platformos-docskit
Description: A platformOS DocsKit built with Gatsby
Author: platformOS
Latest version: 1.2.1

<h1 align="center">
  @platformos/gatsby-theme-platformos-docskit
</h1>

<p align="center">
  <a href="https://www.npmjs.org/package/@platformos/gatsby-theme-platformos-docskit">
    <img src="https://img.shields.io/npm/v/@platformos/gatsby-theme-platformos-docskit.svg" alt="Current npm package version." />
  </a>
  <a href="https://npmcharts.com/compare/@platformos/gatsby-theme-platformos-docskit?minimal=true">
    <img src="https://img.shields.io/npm/dm/@platformos/gatsby-theme-platformos-docskit.svg" alt="Downloads per month on npm." />
  </a>
  <a href="https://npmcharts.com/compare/@platformos/gatsby-theme-platformos-docskit?minimal=true">
    <img src="https://img.shields.io/npm/dt/@platformos/gatsby-theme-platformos-docskit.svg" alt="Total downloads on npm." />
  </a>
</p>

Deploy a best practice and fully customizable documentation site with <a href="https://docskit.platformos.com" target="_blank">platformOS DocsKit</a>.  
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: 
`<Button />`, `<Card />`, `<Grid />`, `<Message />` 

### 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.