@rocketseat/gatsby-theme-docs-core

@rocketseat/gatsby-theme-docs-core

Core theme for @rocketseat/gatsby-theme-docs with no additional theming or style opinions. Includes all of the data structures you need to get up and build a documentation website.

Features • Getting started • Usage • Contributing • License

🚀 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