You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: www/apps/book/app/learn/resources/contribution-guidelines/docs/page.mdx
+80-11Lines changed: 80 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,12 @@ Thank you for your interest in contributing to the documentation! You will be he
10
10
11
11
<Notetitle="Tip">
12
12
13
+
Making a quick fix to a page's content? You can scroll down to the bottom of the page and click on the "Edit this page" link to make quick edits directly in GitHub. If you're making bigger changes, such as adding a new page or making changes to the codebase, check out the rest of this guide.
14
+
15
+
</Note>
16
+
17
+
<Notetitle="Tip">
18
+
13
19
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](https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md).
14
20
15
21
</Note>
@@ -31,11 +37,13 @@ Medusa's documentation projects are all part of the documentation `yarn` workspa
31
37
32
38
The workspace has the following two directories:
33
39
34
-
-`apps`: this directory holds the different documentation websites and projects.
35
-
-`book`: includes the codebase for the [main Medusa documentation](https://docs.medusajs.com/). It's built with [Next.js 15](https://nextjs.org/).
36
-
-`resources`: includes the codebase for the resources documentation, which powers different sections of the docs such as the [Integrations](!resources!/integrations) or [How-to & Tutorials](!resources!/how-to-tutorials) sections. It's built with [Next.js 15](https://nextjs.org/).
37
-
-`api-reference`: includes the codebase for the API reference website. It's built with [Next.js 15](https://nextjs.org/).
38
-
-`ui`: includes the codebase for the Medusa UI documentation website. It's built with [Next.js 15](https://nextjs.org/).
40
+
-`apps`: this directory holds the different documentation websites and projects. All projects are built with [Next.js 15](https://nextjs.org/).
41
+
-`book`: includes the codebase and content for the [main Medusa documentation](../../../page.mdx).
42
+
-`resources`: includes the codebase and content for the resources documentation, which powers different sections of the docs such as the [Integrations](!resources!/integrations) or [How-to & Tutorials](!resources!/how-to-tutorials) sections.
43
+
-`api-reference`: includes the codebase and content for the [API reference](!api!/store).
44
+
-`ui`: includes the codebase and content for the [Medusa UI documentation](!ui!).
45
+
-`user-guide`: includes the codebase and content for the [user guide documentation](!user-guide!).
46
+
-`cloud`: includes the codebase and content for the [Medusa Cloud documentation](!cloud!).
39
47
-`packages`: this directory holds the shared packages and components necessary for the development of the projects in the `apps` directory.
40
48
-`docs-ui` includes the shared React components between the different apps.
41
49
-`remark-rehype-plugins` includes Remark and Rehype plugins used by the documentation projects.
@@ -104,6 +112,53 @@ The UI documentation also shows code examples, which are under the `www/apps/ui/
104
112
105
113
The UI component props are generated from the source code and placed into the `www/apps/ui/specs/components` directory. To contribute to these props and their comments, check the comments in the source code under the `packages/design-system/ui` directory.
106
114
115
+
### Medusa User Guide
116
+
117
+
The content of all pages under the `/user-guide` path are under the `www/apps/user-guide/app` directory.
118
+
119
+
### Medusa Cloud Docs
120
+
121
+
The content of all pages under the `/cloud` path are under the `www/apps/cloud/app` directory.
122
+
123
+
---
124
+
125
+
## Run Documentation Projects Locally
126
+
127
+
To run a documentation project locally, such as `book` or `resources`, change into the directory of that project.
128
+
129
+
Then, copy the `.env.example` file to a new `.env.local` file. This should sufficiently set up the environment variables needed to run the project.
130
+
131
+
Finally, run the `dev` command to start the development server. For example, in the `book` project:
132
+
133
+
```bash npm2yarn
134
+
npm run dev
135
+
```
136
+
137
+
You can then access the documentation site by going to the following URLs in your browser:
138
+
139
+
-`book`: `http://localhost:3000`
140
+
-`resources`: `http://localhost:3000/resources`
141
+
-`api-reference`: `http://localhost:3000/api` (Store API routes at `/api/store` and Admin API routes at `/api/admin`)
142
+
-`ui`: `http://localhost:3000/ui`
143
+
-`user-guide`: `http://localhost:3000/user-guide`
144
+
-`cloud`: `http://localhost:3000/cloud`
145
+
146
+
<Note>
147
+
148
+
When you access the documentation site, you might see errors or warning messages related to missing environment variables of services like Algolia. You can ignore these errors and warnings when working locally.
149
+
150
+
</Note>
151
+
152
+
### Prep Command
153
+
154
+
Each documentation project has a `prep` command that runs scripts to prepare data useful for development or production.
155
+
156
+
The common task that `prep` does is generate the sidebar files, which is useful for both development and production. If you make changes to sidebar items, make sure to run the `prep` command before starting the development server.
157
+
158
+
```bash npm2yarn
159
+
npm run prep
160
+
```
161
+
107
162
---
108
163
109
164
## Style Guide
@@ -114,9 +169,9 @@ When you contribute to the documentation content, make sure to follow the [docum
114
169
115
170
## How to Contribute
116
171
117
-
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).
172
+
If you’re fixing small 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).
118
173
119
-
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.
174
+
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.
120
175
121
176
### Base Branch
122
177
@@ -132,13 +187,27 @@ Make sure that the branch name starts with `docs/`. For example, `docs/fix-servi
132
187
133
188
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`.
134
189
135
-
In the body of the PR, explain clearly what the PR does. If the PR solves an issue, use [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) with the issue number. For example, “Closes #1333”.
190
+
In the body of the PR, explain clearly what the PR does. If the PR solves an issue, use [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) with the issue number. For example, `Closes #1333`.
191
+
192
+
#### Prep Command Before PR
193
+
194
+
If you made changes to the content of any documentation project, you must run the [prep](#prep-command) command in the `book` project before creating a pull request. It will generate the `llms-full.txt` file with the updated content. You should also run it in the project you made changes to, as that will generate other necessary files for the project, such as edit dates.
195
+
196
+
```bash npm2yarn title="www/apps/book"
197
+
npm run prep
198
+
```
199
+
200
+
<Note>
201
+
202
+
Some files are ignored by the script. So, if you don't see that the `llms-full.txt` file is updated after running the `prep` command, you can safely ignore it.
203
+
204
+
</Note>
136
205
137
206
---
138
207
139
208
## Images
140
209
141
-
If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free to include it in the PR. Our team will later upload it to our image hosting.
210
+
If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free to include it in the PR. Our team will later upload it to our image hosting CDN.
142
211
143
212
---
144
213
@@ -244,7 +313,7 @@ If you want to check content ESLint errors locally and fix them, you can do that
244
313
yarn install
245
314
```
246
315
247
-
2\. Run the turbo command in the `www` directory:
316
+
2\. Run the turbo command in the `www` directory or the specific documentation's directory (for example, `www/apps/book`):
248
317
249
318
```bash
250
319
turbo run lint:content
@@ -264,7 +333,7 @@ If you want to check code ESLint errors locally and fix them, you can do that by
264
333
yarn install
265
334
```
266
335
267
-
2\. Run the turbo command in the `www` directory:
336
+
2\. Run the turbo command in the `www` directory or the specific documentation's directory (for example, `www/apps/book`):
0 commit comments