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

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

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 to understand how shadowing works.