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. This will help you 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​

  • All references under the docs/content/referenceCopy to Clipboard directory are automatically generated using Typedoc. So, you can’t contribute to it by making changes to its markdown files.
  • The API reference is generated from OpenApi Spec (OAS) comments added on endpoints in the core Medusa package. So, you can't contribute to it by making changes to files under docs/apiCopy to Clipboard. You can, however, contribute by making changes to the endpoint's comments. Endpoints are located under the packages/medusa/src/apiCopy to Clipboard directory.

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, you need to fork the repository, create a new branch, and make all changes necessary in your repository. Then, once you’re done, create 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 developCopy to Clipboard as the base branch. Make sure to also open your PR against the developCopy to Clipboard branch.

Branch Name​

Make sure that the branch name starts with docs/Copy to Clipboard. For example, docs/fix-servicesCopy 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 www/docs/sidebars.jsCopy to Clipboard. In this file, an object is exported. This object holds more than one sidebar. The properties of the object indicate the internal sidebar name, and the value is an array of sidebar items in that sidebar.

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.

How-to guides in the sidebar for documentation pages under the Commerce Modules section are typically prefixed with one of the following terms:

  • Backend: Copy to Clipboard: Used when the how-to guide explains how to do something on the Medusa backend.
  • Admin: Copy to Clipboard: Used when the how-to guide explains how to do something using the admin APIs.
  • Store: Copy to Clipboard: Used when the how-to guide explains how to do something using the store APIs.

To add an icon to the sidebar item, start by checking if the icon already exists under www/docs/src/theme/IconCopy to Clipboard. If not, add the item as a React component under www/docs/src/theme/Icon/Icon<Name>/index.tsxCopy to Clipboard, where <Name>Copy to Clipboard is the camel-case name of your icon. The icon must be added to the React component as an SVG element. For example:

www/docs/src/theme/Icon/Bolt/index.tsx
import React from "react"

export default function IconBolt(props) {
  return (
    <svg width={20} height={20} viewBox="0 0 20 20" 
      fill="none" xmlns="http://www.w3.org/2000/svg"
      {...props}>
      <path 
        d="M3.125..."
        strokeWidth="1.5" 
        strokeLinecap="round" 
        strokeLinejoin="round"
        stroke="var(--ifm-icon-color)" />
    </svg>
  )
}
Report Incorrect CodeCopy to Clipboard

Make sure to set the strokeCopy to Clipboard or fillCopy to Clipboard of the icon to var(--ifm-icon-color)Copy to Clipboard as shown in the example above.

If you added a new icon, add it in the object in the file www/docs/src/theme/Icon/index.tsCopy to Clipboard, where the property is the kebab-case version of the icon's name, and the value being the component you created. Make sure to add it in the correct alphabetical position as well. For example:

www/docs/src/theme/Icon/index.ts
import IconBolt from "./Bolt"
import IconBoltSolid from "./BoltSolid"
// other imports

export default {
  // other icons
  "bolt": IconBolt,
  "bolt-solid": IconBoltSolid,
  // other icons
}
Report Incorrect CodeCopy to Clipboard

Finally, you can add the icon to the sidebar item by adding a sidebar_iconCopy to Clipboard property to the customPropsCopy to Clipboard property and setting its value to the kebab-cased version of the icon's name. For example:

www/docs/sidebars.js
module.exports = {
  // other sidebars
  homepage: [
    {
      // other properties
      customProps: {
        sidebar_icon: "book-open",
      },
    },
    // other items
  ],
}
Report Incorrect CodeCopy to Clipboard

There are different sidebar item types used in the documentation:

  • Homepage Items: If a sidebar item is shown under the homepageCopy to Clipboard sidebar, you should set the classNameCopy to Clipboard property of the item to homepage-sidebar-itemCopy to Clipboard. You can use this with other sidebar item types. For example:

    www/docs/sidebars.js
    module.exports = {
      // other sidebars
      homepage: [
        {
          type: "doc",
          // other properties
          className: "homepage-sidebar-item",
        },
        // other items
      ],
    }
    Report Incorrect CodeCopy to Clipboard

  • Sidebar Title: This item is used as a title to the sidebar, typically added at the top of the sidebar. You typically would also use an icon with it. To use this item, add a sidebar_is_titleCopy to Clipboard property to the customPropsCopy to Clipboard object of the item with its value being trueCopy to Clipboard. For example:

    www/docs/sidebars.js
    module.exports = {
      // other sidebars
      modules: [
        // other items
        {
          type: "doc",
          id: "modules/overview",
          label: "Commerce Modules",
          customProps: {
            sidebar_is_title: true,
            sidebar_icon: "puzzle",
          },
        },
        // other items
      ],
    }
    Report Incorrect CodeCopy to Clipboard

  • Back Item: This item is used to show a back button, typically at the top of the sidebar. To use this item, add the sidebar_is_back_linkCopy to Clipboard property to the customPropsCopy to Clipboard object of the item, with its value set to true. Also, add the sidebar_iconCopy to Clipboard property to the customPropsCopy to Clipboard object with its value set to back-arrowCopy to Clipboard. For example:

    www/docs/sidebars.js
    module.exports = {
      // other sidebars
      core: [
        // other items
        {
          type: "ref",
          id: "homepage",
          label: "Back to home",
          customProps: {
            sidebar_is_back_link: true,
            sidebar_icon: "back-arrow",
          },
        },
        // other items
      ],
    }
    Report Incorrect CodeCopy to Clipboard

  • Group Divider Item: This item is used if a sidebar item does not link to any document and is only used to separate between sidebar sections. The item must be of type htmlCopy to Clipboard, and its valueCopy to Clipboard property holds the text that should be shown in the divider. You must also add in the customPropsCopy to Clipboard object of the item the property sidebar_is_group_dividerCopy to Clipboard with its value being trueCopy to Clipboard. For example:

    www/docs/sidebars.js
    module.exports = {
      // other sidebars
      homepage: [
        // other items
        {
          type: "html",
          value: "Browse Docs",
          customProps: {
            sidebar_is_group_divider: true,
          },
          className: "homepage-sidebar-item",
        },
        // other items
      ],
    }
    Report Incorrect CodeCopy to Clipboard

  • Group Headline Item: This item is used if a sidebar item does not link to any document and is only used to indicate the beginning of a new section or group in the sidebar. To use this item, set the typeCopy to Clipboard of the item to categoryCopy to Clipboard, and add the sidebar_is_group_headlineCopy to Clipboard property to the customPropsCopy to Clipboard object of the item, with its value set to trueCopy to Clipboard. For example:

    www/docs/sidebars.js
    module.exports = {
      // other sidebars
      modules: [
        // other items
        {
          type: "category",
          label: "Regions and Currencies",
          collapsible: false,
          customProps: {
            sidebar_is_group_headline: true,
          },
          items: [
            // items within group or section
          ],
        },
        // other items
      ],
    }
    Report Incorrect CodeCopy to Clipboard

  • Soon Item: This item is used to indicate that a certain guide will be added soon, but it does not actually link to any document. To use this item, set the typeCopy to Clipboard of the item to linkCopy to Clipboard, its hrefCopy to Clipboard property to #Copy to Clipboard, and add to the customPropsCopy to Clipboard object the property sidebar_is_soonCopy to Clipboard with its value set to trueCopy to Clipboard. For example:

    www/docs/sidebars.js
    module.exports = {
      // other sidebars
      modules: [
        // other items
        {
          type: "link",
          href: "#",
          label: "Currencies",
          customProps: {
            sidebar_is_soon: true,
          },
        },
        // other items
      ],
    }
    Report Incorrect CodeCopy to Clipboard

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 dangerCopy to Clipboard admonition based on how critical it is.

If the note displays helpful information and tips that may not be in the scope of the documentation page, use the tipCopy to Clipboard admonition.

For all other note types, use the noteCopy to Clipboard admonition.

Images​

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

Code Blocks​

Use Tabs with Code Blocks​

To use Tabs with Code Blocks, you have to use Docusaurus's TabsCopy to Clipboard and TabItemCopy to Clipboard components.

You must also pass to the TabsCopy to Clipboard component the prop isCodeTabs={true}Copy to Clipboard to ensure correct styling.

For example:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.uploads.create(file) // file is an instance of File
.then(({ uploads }) => {
  const key = uploads[0].key
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X POST '<BACKEND_URL>/admin/uploads' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: text/csv' \
  -F 'files=@"<FILE_PATH_1>"'
```

</TabItem>
</Tabs>
Report Incorrect CodeCopy to Clipboard

Add Title to Code Block with Tabs​

If you want to add a title to a code block with tabs, add the codeTitleCopy to Clipboard prop to the TabsCopy to Clipboard component.

For example:

<Tabs 
  groupId="request-type"
  isCodeTabs={true}
  codeTitle="/src/services/hello.ts">
Report Incorrect CodeCopy to Clipboard

Add Title to Code Block without Tabs​

To add a title to a code block without tabs:

```js title=src/index.ts
console.log("hello")
```
Report Incorrect CodeCopy to Clipboard

Remove Report Button​

Some code block don't need a report button. To remove the report button, use the noReportCopy to Clipboard metadata.

For example:

```bash noReport
medusa new my-medusa-store
```
Report Incorrect CodeCopy to Clipboard

Remove Copy Button​

Some code blocks don't need a copy button. To remove the copy button, use the noCopyCopy to Clipboard metadata:

For example:

```bash noCopy
medusa new my-medusa-store
```
Report Incorrect CodeCopy to Clipboard

NPM and Yarn Code Blocks​

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

For example:

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

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

Expand Commands​

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

Run Command​

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

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

Global Option​

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

yarn global add @medusajs/medusa-cli
Report Incorrect CodeCopy to Clipboard

Linting with Vale​

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

Result of Vale 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. Changing to the docsCopy to Clipboard directory:
cd docs
Report Incorrect CodeCopy to Clipboard

3. Running the run-valeCopy to Clipboard script:

./run-vale.sh error
Report Incorrect CodeCopy 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 mdCopy to Clipboard or mdxCopy to Clipboard files:

<!-- vale off -->

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

<!-- vale on -->
Report Incorrect CodeCopy to Clipboard

You can also disable specific rules. For example:

<!-- vale docs.Numbers = NO -->

Medusa supports Node versions 14 and 16.

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

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

Linting with ESLint​

Medusa uses ESlint to lint code blocks in the documentation and perform checks on incoming PRs into the repository.

Result of ESLint PR Checks​

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

Running ESLint locally​

If you want to check ESLint errors locally and fix them, you can do that by:

  1. Installing the dependencies in the root directory:
yarn install
Report Incorrect CodeCopy to Clipboard

2. Run the lint command:

yarn lint:docs --fix
Report Incorrect CodeCopy to Clipboard

The --fixCopy to Clipboard option automatically fixes some errors. Other errors will be shown which you'll have to resolve yourself.

ESLint Exceptions​

If some code blocks have errors that can't or shouldn't be fixed, you can add the following command before the code block:

<!-- eslint-skip -->

```js
console.log("This block isn't linted")
```

```js
console.log("This block is linted")
```
Report Incorrect CodeCopy to Clipboard

You can also disable specific rules. For example:

<!-- eslint-disable semi -->

```js
console.log("This block can use semicolons");
```

```js
console.log("This block can't use semi colons")
```
Report Incorrect CodeCopy to Clipboard

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.

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.