How to Create a Guide

Creating a new guide for Chakra UI takes four steps:

  1. Create your guide file
  2. Add frontmatter
  3. Write your guide content
  4. Open a pull request

Create your guide file#

Create a file in website/guides with a filename that briefly describes your guide in kebab case. For example, the path to this guide (the one you're reading) is website/guides/how-to-create-a-guide.mdx.

Add frontmatter#

In order for your guide to work correctly, you must create a frontmatter block at the top of the file. The frontmatter block provides data about your guide to our documentation system (gatsby) that is used to generate your guide's listing on the main guides page.

Your frontmatter block should specify a title, a description, your GitHub username (as creator), and (optionally) a tags array. Here's the frontmatter block for this guide:

---
title: How to Create a Guide
description: A guide for creating a Chakra UI guide
tags: ["meta"]
author: with-heart
---

The frontmatter block must include the opening and closing --- lines.

Write your guide content#

Our guides are written using MDX. MDX is JSX in Markdown.

If you're new to Markdown or MDX, here are a few resources to help you get started:

You can also open the .mdx file for this guide or any other Chakra UI guide for inspiration.

Open a pull request#

Once you've created your guide, the final step is to open a pull request to the Chakra UI repository. You'll need to fork the Chakra repo, push your changes to a branch on your fork, and then open a pull request from your fork to the Chakra repo.

In your pull request description, please provide a brief overview of your guide.

If you're unfamiliar with how forks or pull requests work, check out How To: Fork a GitHub Repository & Submit a Pull Request by Jake Jarvis.

Additionally, you can find more information relating to forks and PRs in the following documentation from the GitHub website: