on GitHub" data-tooltip-id=":R1blcldb:">v2.5.1·Edited Dec 12·
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.
Medusa's documentation projects are all part of the documentation yarn workspace, which you can find in the medusa repository under the www
directory.
The workspace has the following two directories:
apps
: this directory holds the different documentation websites and projects.
book
: includes the codebase for the main Medusa documentation. It's built with Next.js 15.resources
: includes the codebase for the Medusa Development Resources documentation. It's built with Next.js 15.api-reference
: includes the codebase for the API reference website. It's built with Next.js 15.ui
: includes the codebase for the Medusa UI documentation website. It's built with Next.js 15.packages
: this directory holds the shared packages and components necessary for the development of the projects in the apps
directory.
docs-ui
includes the shared React components between the different apps.remark-rehype-plugins
includes Remark and Rehype plugins used by the documentation projects.All documentation projects are built with Next.js. The content is writtin in MDX files.
The content of the Medusa main docs are under the www/apps/book/app
directory.
The content of the Medusa Resources documentation are under the www/apps/resources/app
directory.
www/apps/resources/references
directory are generated automatically from the source code under the packages/medusa
directory. So, you can't directly make changes to them. Instead, you'll have to make changes to the comments in the original source code.The API reference's content is split into two types:
www/apps/api-reference/markdown
directory. They are MDX files.www/utils/generated/oas-output
directory.The content of the Medusa UI documentation are located under the www/apps/ui/src/content/docs
directory. They are MDX files.
The UI documentation also shows code examples, which are under the www/apps/ui/src/examples
directory.
The UI component props are generated from the source code and placed into the www/apps/ui/src/specs
directory. To contribute to these props and their comments, check the comments in the source code under the packages/design-system/ui
directory.
When you contribute to the documentation content, make sure to follow the documentation style guide.
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, create a PR in the Medusa repository.
When you make an edit to an existing documentation page or fork the repository to make changes to the documentation, create a new branch.
Documentation contributions always use develop
as the base branch. Make sure to also open your PR against the develop
branch.
Make sure that the branch name starts with docs/
. For example, docs/fix-services
. Vercel deployed previews are only triggered for branches starting with docs/
.
When you create a pull request, prefix the title with docs:
or docs(PROJECT_NAME):
, where PROJECT_NAME
is the name of the documentation project this pull request pertains to. For example, docs(ui): fix titles
.
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”.
If you are adding images to a documentation page, you can host the image on Imgur for free to include it in the PR. Our team will later upload it to our image hosting.
If you’re adding code blocks that use NPM and Yarn, you must add the npm2yarn
meta field.
For example:
The code snippet must be written using NPM.
When a command uses the global option -g
, add it at the end of the NPM command to ensure that it’s transformed to a Yarn command properly. For example:
Medusa uses Vale to lint documentation pages and perform checks on incoming PRs into the repository.
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.
If you want to check your work locally, you can do that by:
www/vale
directory:3. Running the run-vale
script:
Medusa uses ESlint to lint code blocks both in the content and the code base of the documentation apps.
Each PR runs through a check that lints the code in the content files using ESLint. The action's name is content-eslint
.
If you want to check content ESLint errors locally and fix them, you can do that by:
1. Install the dependencies in the www
directory:
2. Run the turbo command in the www
directory:
This will fix any fixable errors, and show errors that require your action.
Each PR runs through a check that lints the code in the content files using ESLint. The action's name is code-docs-eslint
.
If you want to check code ESLint errors locally and fix them, you can do that by:
1. Install the dependencies in the www
directory:
2. Run the turbo command in the www
directory:
This will fix any fixable errors, and show errors that require your action.