Skip to main content

Contribution Guidelines

Thank you for your interest in contributing to the documentation! You will be helping the open source community and other developers interested in learning more about Medusa and using it.

This guide is specific to contributing to the documentation. If you’re interested in contributing to Medusa’s codebase, check out the contributing guidelines in the Medusa GitHub repository.

Site Setup

The documentation website is built with Docusaurus, a framework that optimizes documentation creation. If you’re not familiar with Docusaurus, it’s recommended to check out the Installation documentation on their website to better understand Docusaurus, how it works, its structure, and more details.

The documentation codebase is hosted as part of the medusa repository on GitHub. You’ll find the code that runs the docusaurus website under the www/docs directory.

Documentation Content

The documentation content is written in Markdown format and is located in the docs/content directory of the same repository. If you’re not familiar with Markdown, check out this cheat sheet for a quick start.

You’ll also find MDX files. MDX files combine the power of Markdown with React. So, the content of the file can contain JSX components and import statements, among other features. You can learn more about MDX in docusaurus’s guide.

What You Can Contribute To

  • You can contribute to the Docusaurus codebase to add a new feature or fix a bug in the documentation website.
  • You can contribute to the documentation content either by fixing errors you find or by adding documentation pages.

What You Can’t Contribute To

The Services Reference is an automatically generated API reference using Typedoc. So, you can’t contribute to it by making changes to its markdown files.

You can, however, contribute to the script generating it if you find any issues in it.

Style Guide

When you contribute to the documentation content, make sure to follow the documentation style guide.

How to Contribute

If you’re fixing errors in an existing documentation page, you can scroll down to the end of the page and click on the “Edit this page” link. You’ll be redirected to the GitHub edit form of that page and you can make edits directly and submit a pull request (PR).

If you’re adding a new page or contributing to the codebase, fork the repository, create a new branch, and make all changes necessary in your repository. Then, once you’re done creating a PR in the Medusa repository.

For more details on how to contribute, check out the contribution guidelines in the Medusa repository.

Base Branch

When you make an edit to an existing documentation page or fork the repository to make changes to the documentation, you have to create a new branch.

Documentation contributions always use Copy to Clipboard as the base branch.

Branch Name

Make sure that the branch name starts with Copy to Clipboard. For example, Copy to Clipboard.

Pull Request Conventions

When you create a pull request, prefix the title with “docs:”. Make sure to keep “docs” in small letters.

In the body of the PR, explain clearly what the PR does. If the PR solves an issue, use closing keywords with the issue number. For example, “Closes #1333”.

When you add a new page to the documentation, you must add the new page in Copy to Clipboard under the Copy to Clipboard. You can learn more about the syntax used here.

Terminology

When the documentation page is a conceptual or an overview documentation, the label in the sidebar should start with a noun.

When the documentation page is tutorial documentation, the label in the sidebar should start with a verb. Exceptions to this rule are integration documentation and upgrade guides.

Character Count

The character count of the sidebar item's label must be at most twenty-seven characters. For the API Reference, the sidebar item's label must be at most twenty-five characters.

Notes and Additional Information

When displaying notes and additional information on a documentation page, use Admonitions. Make sure the type of admonition used matches the note’s importance to the current document.

If the note is something developers have to be careful of doing or not doing, use the Copy to Clipboard or Copy to Clipboard admonitions based on how critical it is.

If the note is defining something to the developer in case they’re not familiar with it, use the Copy to Clipboard admonition.

If the note displays helpful information and tips use the Copy to Clipboard admonition.

If the admonition does not match any of the mentioned criteria, always default to the Copy to Clipboard admonition.

Images

If you are adding images to a documentation page, you can host the image on Imgur for free.

Code Block Types

In the Medusa documentation, there are two code block types: code blocks with headers and code blocks without headers.

Code blocks without headers should be used when:

  • The code block is used inside an Admonition.
  • The content of the code block can't be reported (for example, if the code block contains only a text of the expected output).

In all other cases, code blocks with headers should be used.

Code Blocks with Headers

By default, all code blocks have headers and no additional actions are required to add the header.

Code Blocks without Headers

To add a code block without a header, simply add Copy to Clipboard after the beginning backticks of the code block. For example:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
```bash noHeader
this code block does not have a header
```
Copy to Clipboard

Copy to Clipboard should be added after the language of the code block (which is Copy to Clipboard in the above example). If you used Copy to Clipboard as well, Copy to Clipboard should be after it.

NPM and Yarn Code Blocks

If you’re adding code blocks that use NPM and Yarn, you must use the npm2yarn syntax.

For example:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
```bash npm2yarn
npm run start
```
Copy to Clipboard

The code snippet must be written using NPM, and the Copy to Clipboard plugin will automatically transform it to Yarn.

Expand Commands

Don't use commands in their abbreviated terms. For example, instead of Copy to Clipboard use Copy to Clipboard.

Run Command

Make sure to always use the Copy to Clipboard command when the command runs a script.

For example, even though you can run the Copy to Clipboard script using NPM with Copy to Clipboard, however, to make sure it’s transformed properly to a Yarn command, you must add the Copy to Clipboard keyword before Copy to Clipboard.

Global Option

When a command uses the global option Copy to Clipboard, add it at the end of the NPM command to ensure that it’s transformed to a Yarn command properly. For example:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
npm install @medusajs/medusa-cli -g
Copy to Clipboard

Linting with Vale

Medusa uses Vale to lint documentation pages and perform checks on incoming PRs into the repository.

Result of PR Checks

You can check the result of running the "lint" action on your PR by clicking the Details link next to it. You can find there all errors that you need to fix.

Run Vale Locally

If you want to check your work locally, you can do that by:

  1. Installing Vale on your machine.
  2. Change to the Copy to Clipboard directory:
Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
cd docs
Copy to Clipboard

3. Run the Copy to Clipboard script:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
./run-vale.sh error
Copy to Clipboard

VS Code Extension

To facilitate writing documentation, you can optionally use the Vale VS Code extension. This will show you any errors in your documentation while writing it.

Linter Exceptions

If it's needed to break some style guide rules in a document, you can wrap the parts that the linter shouldn't scan with the following comments in the Copy to Clipboard or Copy to Clipboard files:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
<!-- vale off -->

content that shouldn't be scanned for errors here...

<!-- vale on -->
Copy to Clipboard

You can also disable specific rules. For example:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
<!-- vale docs.Numbers = NO -->

Medusa supports Node versions 14 and 16.

<!-- vale docs.Numbers = YES -->
Copy to Clipboard

If you use this in your PR, you must justify its usage.

Need Additional Help

If you need any additional help while contributing, you can join Medusa's Discord server and ask Medusa’s core team as well as the community any questions.