Black Lives Matter. Support the Equal Justice Initiative.
Skip to main contentCarbon Design System

Documentation

You can contribute to the content on the Carbon site in a few different ways. Choose the way that works best, depending on how extensive your contribution is. And be sure to read our content writing guidelines before you begin!

Editing pages

The easiest way to edit a page is with the Edit this page on Github link that appears at the bottom of every page on the site. The link opens the specific Github page where you can edit the content and then propose the change with a pull request.

Alternatively, if you have a specific fix or contribution, you can fork the repo and generate a pull request.

Making regular content updates

If you are planning regular or more comprehensive content updates, you’ll want to fork the repo and install some of the tools we use to build the website. This will create an easier workflow for you long term.

Instructions for how to install tools and fork the repo.

Instructions for how to update content with VSCode.

Content and style guidelines

Before you get started, take a moment to review our content guidelines. Following these will help us ensure consistency of experience across the site.

Use Markdown

The website is written in Markdown, which makes it easy for anyone to contribute content in a systematic way. If you don’t already have a Markdown editor installed, there are plenty of free editors available online.

Check out Carbon’s handy markdown styling cheatsheet for how to style content.

Guidelines for writing content

Please keep these things in mind when writing content for Carbon.

  • Aim for a friendly and encouraging tone.
  • Speak directly to the user. You can use the second person pronoun (“you”).
  • Keep sentences and paragraphs short and focused.
  • Be clear and concise by removing unnecessary words. The more concise the text, the easier it is for all users to understand.
  • Use sentence case for everything, including component names, e.g. Content switcher and Data table.

To learn about writing content for component pages, see our production guidelines.