🚀 Features

• MDX for docs;
• Sidebar customization with Yaml;

⚡️ Getting started

Using Yarn:

yarn add @rocketseat/gatsby-theme-docs-core

Using NPM:

npm i @rocketseat/gatsby-theme-docs-core

🔥 Usage

Theme options

| Key | Default | Required | Description | | ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | basePath | / | No | Root url for all docs | | configPath | config | No | Location of config files | | docsPath | docs | No | The site description for SEO and social (FB, Twitter) tags | | githubUrl | - | - | Deprecated in favor of repositoryUrl | | repositoryUrl | - | No | The URL of your repository (supports GitHub, GitLab and Bitbucket). Example: https://github/jpedroschmitz/rocketdocs | | baseDir | - | No | If your Gatsby site does not live in the root of your project directory/git repo, pass the subdirectory name here (docs, for example) | | withMdx | true | No | If necessary, you can add your own MDX options to the theme. To do so, make sure you turn this option to false and include gatsby-plugin-mdx on your gatsby-config | | branch | main | No | Default branch of the repository |

Note: When adding a BitBucket link on the repositoryUrl option, don't add the src/<branch> to it. Example of correct link: https://bitbucket.org/jpedroschmitz/rocketdocs

Example usage

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `@rocketseat/gatsby-theme-docs-core`,
      options: {
        basePath: `documentation`,
        configPath: `config`,
        docsPath: `docs`,
        githubUrl: `https://github.com/jpedroschmitz/rocketdocs`,
        baseDir: `www`,
      },
    },
  ],
};

Navigation

The sidebar is highly customizable, you can create a file under the config folder named sidebar.yml. If you add a basePath in the theme options, you don't need to add it before the links, the useSidebar hook will append it.

Here is an example:

# Simple item
- label: 'Home'
  link: '/'
# With list of subitems
- label: 'With dropdown'
  items:
    - label: 'My Example'
      link: '/my-example'

useSidebar

To get all the sidebar items, you can use the useSidebar hook. Example:

import React from 'react';
import { useSidebar } from '@rocketseat/gatsby-theme-docs-core';

export default function Sidebar() {
  const data = useSidebar();

  console.log(data);
  /*
    [
      {
        "node": {
          "label": "Home",
          "link": "/",
          "items": null,
          "id": "a2913be3-af3c-5fc9-967e-a058e86b20a9"
        }
      },
      {
        "node": {
          "label": "With dropdown",
          "link": null,
          "items": [{ "label": "My Example", "link": "/my-example" }],
          "id": "c7d9606c-4bda-5097-a0df-53108e9f4efd"
        }
      }
    ]
  */
}

Docs Fields

Inside your docs folder, you can create MDX files. The filename will be the page path.

Add a title to the frontmatter of the MDX file and place the content below it. For example:

---
title: 'My Example'
description: 'A simple description for this page'
image: 'banner.png'
disableTableOfContents: false
---

Your amazing page

Every file must have a custom title. Description and image are not required.

Shadowing

Check the Shadowing in Gatsby Themes docs to understand how to customize this theme!

In general, you will need to create two files (Docs.js and Homepage.js) into src/@rocketseat/gatsby-theme-docs-core/components/templates to shadow/override it.

✨ Contributing

Thanks for being interested in contributing! We’re so glad you want to help! Please take a little bit of your time and look at our contributing guidelines and our code of conduct! All type of contributions are welcome, such as bug fixes, issues or feature requests.

📝 License

Licensed under the MIT License.

Made with 💜 by João Pedro