asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: changes to main docs sidebar (#11750)

Browse Source 
* docs: changes to main docs sidebar

* fix links

* fix vale test

* fix vale errors
This commit is contained in:
Shahed Nasser
2025-03-06 11:55:56 +02:00
committed by GitHub
parent eba3172d88
commit ecc3deb362
32 changed files with 12622 additions and 12194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/contribution-guidelines/admin-translations/page.mdx
-107
View File
@@ -1,107 +0,0 @@
export const metadata = {
title: `Translate Medusa Admin`,
}
# {metadata.title}
The Medusa Admin supports multiple languages, with the default being English. In this documentation, you'll learn how to contribute to the community by translating the Medusa Admin to a language you're fluent in.
{/* vale docs.We = NO */}
You can contribute either by translating the admin to a new language, or fixing translations for existing languages. As we can't validate every language's translations, some translations may be incorrect. Your contribution is welcome to fix any translation errors you find.
{/* vale docs.We = YES */}
<Note>
Check out the translated languages either in the admin dashboard's settings or on [GitHub](https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/i18n/languages.ts).
</Note>
---
## How to Contribute Translation
1. Clone the [Medusa monorepository](https://github.com/medusajs/medusa) to your local machine:
```bash
git clone https://github.com/medusajs/medusa.git
```
If you already have it cloned, make sure to pull the latest changes from the `develop` branch.
2. Install the monorepository's dependencies. Since it's a Yarn workspace, it's highly recommended to use yarn:
```bash
yarn install
```
3. Create a branch that you'll use to open the pull request later:
```bash
git checkout -b feat/translate-<LANGUAGE>
```
Where `<LANGUAGE>` is your language name. For example, `feat/translate-da`.
4. Translation files are under `packages/admin/dashboard/src/i18n/translations` as JSON files whose names are the ISO-2 name of the language.
- If you're adding a new language, copy the file `packages/admin/dashboard/src/i18n/translations/en.json` and paste it with the ISO-2 name for your language. For example, if you're adding Danish translations, copy the `en.json` file and paste it as `packages/admin/dashboard/src/i18n/translations/de.json`.
- If you're fixing a translation, find the JSON file of the language under `packages/admin/dashboard/src/i18n/translations`.
5. Start translating the keys in the JSON file (or updating the targeted ones). All keys in the JSON file must be translated, and your PR tests will fail otherwise.
- You can check whether the JSON file is valid by running the following command in `packages/admin/dashboard`, replacing `da.json` with the JSON file's name:
```bash title="packages/admin/dashboard"
yarn i18n:validate da.json
```
6. After finishing the translation, if you're adding a new language, import its JSON file in `packages/admin/dashboard/src/i18n/translations/index.ts` and add it to the exported object:
```ts title="packages/admin/dashboard/src/i18n/translations/index.ts" highlights={[["2"], ["6"], ["7"], ["8"]]}
// other imports...
import da from "./da.json"
export default {
// other languages...
da: {
translation: da,
},
}
```
The language's key in the object is the ISO-2 name of the language.
7. If you're adding a new language, add it to the file `packages/admin/dashboard/src/i18n/languages.ts`:
export const languageHighlights = [
["7", "code", "The ISO-2 name of the language."],
["8", "display_name", "The language's name to be displayed in the admin."],
["9", "ltr", "Whether the language supports a left-to-right layout."],
["10", "date_locale", "An instance of the locale imported from the [date-fns/locale](https://date-fns.org/) package."]
]
```ts title="packages/admin/dashboard/src/i18n/languages.ts" highlights={languageHighlights}
import { da } from "date-fns/locale"
// other imports...
export const languages: Language[] = [
// other languages...
{
code: "da",
display_name: "Danish",
ltr: true,
date_locale: da,
},
]
```
`languages` is an array having the following properties:
- `code`: The ISO-2 name of the language. For example, `da` for Danish.
- `display_name`: The language's name to be displayed in the admin.
- `ltr`: Whether the language supports a left-to-right layout. For example, set this to `false` for languages like Arabic.
- `date_locale`: An instance of the locale imported from the [date-fns/locale](https://date-fns.org/) package.
8. Once you're done, push the changes into your branch and open a pull request on GitHub.
Our team will perform a general review on your PR and merge it if no issues are found. The translation will be available in the admin after the next release.
www/apps/resources/app/contribution-guidelines/docs/page.mdx
-259
View File
@@ -1,259 +0,0 @@
export const metadata = {
title: `Docs Contribution Guidelines`,
}
# {metadata.title}
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.
<Note title="Tip">
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).
</Note>
## Documentation Workspace
Medusa's documentation projects are all part of the documentation yarn workspace, which you can find in the [medusa repository](https://github.com/medusajs/medusa) 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](https://docs.medusajs.com/). It's built with [Next.js 15](https://nextjs.org/).
- `resources`: includes the codebase for the Medusa Development Resources documentation. It's built with [Next.js 15](https://nextjs.org/).
- `api-reference`: includes the codebase for the API reference website. It's built with [Next.js 15](https://nextjs.org/).
- `ui`: includes the codebase for the Medusa UI documentation website. It's built with [Next.js 15](https://nextjs.org/).
- `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.
---
## Documentation Content
All documentation projects are built with Next.js. The content is writtin in MDX files.
### Medusa Main Docs Content
The content of the Medusa main docs are under the `www/apps/book/app` directory.
### Medusa Development Resources Content
The content of the Medusa Resources documentation are under the `www/apps/resources/app` directory.
<Note>
Documentation pages under the `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.
</Note>
### API Reference
The API reference's content is split into two types:
1. Static content, which are the content related to getting started, expanding fields, and more. These are located in the `www/apps/api-reference/markdown` directory. They are MDX files.
2. OpenAPI specs that are shown to developers when checking the reference of an API Route. These are generated from OpenApi Spec comments, which are under the `www/utils/generated/oas-output` directory.
### Medusa UI Documentation
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.
---
## Style Guide
When you contribute to the documentation content, make sure to follow the [documentation style guide](https://www.notion.so/Style-Guide-Docs-fad86dd1c5f84b48b145e959f36628e0).
---
## 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, create a PR 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, create a new branch.
Documentation contributions always use `develop` as the base branch. Make sure to also open your PR against the `develop` branch.
### Branch Name
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/`.
### Pull Request Conventions
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](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”.
---
## Images
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.
---
## NPM and Yarn Code Blocks
If you’re adding code blocks that use NPM and Yarn, you must add the `npm2yarn` meta field.
For example:
~~~md
```bash npm2yarn
npm run start
```
~~~
The code snippet must be written using NPM.
### Global Option
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:
```bash npm2yarn
npm install @medusajs/cli -g
```
---
## Linting with Vale
Medusa uses [Vale](https://vale.sh/) 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](https://vale.sh/docs/vale-cli/installation/) on your machine.
2. Changing to the `www/vale` directory:
```bash
cd www/vale
```
3\. Running the `run-vale` script:
```bash
# to lint content for the main documentation
./run-vale.sh docs content error references
# to lint content for the API reference
./run-vale.sh api-reference app/_mdx error
# to lint content for the Medusa UI documentation
./run-vale.sh ui src/content/docs error
```
{/* TODO need to enable MDX v1 comments first. */}
{/* ### 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 `md` or `mdx` files:
```md
<!-- vale off -->
content that shouldn't be scanned for errors here...
<!-- vale on -->
```
You can also disable specific rules. For example:
```md
<!-- vale docs.Numbers = NO -->
Medusa supports Node versions 14 and 16.
<!-- vale docs.Numbers = YES -->
```
If you use this in your PR, you must justify its usage. */}
---
## Linting with ESLint
Medusa uses ESlint to lint code blocks both in the content and the code base of the documentation apps.
### Linting Content with ESLint
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:
```bash
yarn install
```
2\. Run the turbo command in the `www` directory:
```bash
turbo run lint:content
```
This will fix any fixable errors, and show errors that require your action.
### Linting Code with ESLint
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:
```bash
yarn install
```
2\. Run the turbo command in the `www` directory:
```bash
yarn lint
```
This will fix any fixable errors, and show errors that require your action.
{/* TODO need to enable MDX v1 comments first. */}
{/* ### 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:
~~~md
<!-- eslint-skip -->
```js
console.log("This block isn't linted")
```
```js
console.log("This block is linted")
```
~~~
You can also disable specific rules. For example:
~~~md
<!-- eslint-disable semi -->
```js
console.log("This block can use semicolons");
```
```js
console.log("This block can't use semi colons")
```
~~~ */}
www/apps/resources/app/usage/page.mdx
-100
View File
@@ -1,100 +0,0 @@
export const metadata = {
title: `Usage Information`,
}
# {metadata.title}
At Medusa, we strive to provide the best experience for developers using our platform. For that reason, Medusa collects anonymous and non-sensitive data that provides a global understanding of how users are using Medusa.
---
## Purpose
As an open source solution, we work closely and constantly interact with our community to ensure that we provide the best experience for everyone using Medusa.
We are capable of getting a general understanding of how developers use Medusa and what general issues they run into through different means such as our Discord server, GitHub issues and discussions, and occasional one-on-one sessions.
However, although these methods can be insightful, they’re not enough to get a full and global understanding of how developers are using Medusa, especially in production.
Collecting this data allows us to understand certain details such as:
- What operating system do most Medusa developers use?
- What version of Medusa is widely used?
- What parts of the Medusa Admin are generally undiscovered by our users?
- How much data do users manage through our Medusa Admin? Is it being used for large number of products, orders, and other types of data?
- What Node version is globally used? Should we focus our efforts on providing support for versions that we don’t currently support?
---
## Medusa Application Analytics
This section covers which data in the Medusa application are collected and how to opt out of it.
### Collected Data in the Medusa Application
The following data is being collected on your Medusa application:
- Unique project ID generated with UUID.
- Unique machine ID generated with UUID.
- Operating system information including Node version or operating system platform used.
- The version of the Medusa application and Medusa CLI are used.
<Note>
Data is only collected when the Medusa application is run with the command `medusa start`.
</Note>
### How to Opt Out
If you prefer to disable data collection, you can do it either by setting the following environment variable to true:
```bash
MEDUSA_DISABLE_TELEMETRY=true
```
Or, you can run the following command in the root of your Medusa application project to disable it:
```bash
npx medusa telemetry --disable
```
---
## Admin Analytics
This section covers which data in the admin are collected and how to opt out of it.
### Collected Data in Admin
<Note>
Users have the option to [enable or disable the anonymization](#how-to-enable-anonymization) of the collected data.
</Note>
The following data is being collected on your admin:
- The name of the store.
- The email of the user.
- The total number of products, orders, discounts, and users.
- The number of regions and their names.
- The currencies used in the store.
- Errors that occur while using the admin.
### How to Enable Anonymization
To enable anonymization of your data from the Medusa Admin:
1. Go to Settings → Personal Information.
2. In the Usage insights section, click on the “Edit preferences” button.
3. Enable the "Anonymize my usage data” toggle.
4. Click on the “Submit and close” button.
### How to Opt-Out
To opt out of analytics collection in the Medusa Admin, set the following environment variable:
```bash
MEDUSA_FF_ANALYTICS=false
```
www/apps/resources/generated/edit-dates.mjs
-3
View File
@@ -99,7 +99,6 @@ export const generatedEditDates = {
"app/commerce-modules/user/user-creation-flows/page.mdx": "2025-02-26T11:35:54.685Z",
"app/commerce-modules/user/page.mdx": "2025-02-26T11:18:00.382Z",
"app/commerce-modules/page.mdx": "2024-12-23T14:38:21.064Z",
"app/contribution-guidelines/docs/page.mdx": "2024-12-12T11:06:12.250Z",
"app/create-medusa-app/page.mdx": "2025-01-16T10:00:25.975Z",
"app/deployment/admin/vercel/page.mdx": "2024-10-16T08:10:29.377Z",
"app/deployment/medusa-application/railway/page.mdx": "2025-02-24T07:35:43.421Z",
@@ -188,7 +187,6 @@ export const generatedEditDates = {
"app/troubleshooting/general-errors/page.mdx": "2024-05-03T17:36:38+03:00",
"app/troubleshooting/s3/page.mdx": "2025-01-24T13:47:24.994Z",
"app/troubleshooting/page.mdx": "2025-02-26T11:40:54.162Z",
"app/usage/page.mdx": "2025-02-26T11:49:39.213Z",
"app/page.mdx": "2025-02-26T10:23:58.440Z",
"app/commerce-modules/auth/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/auth/auth-flows/page.mdx": "2025-01-13T11:31:35.361Z",
@@ -3144,7 +3142,6 @@ export const generatedEditDates = {
"references/product/interfaces/product.FilterableProductProps/page.mdx": "2025-02-24T10:48:41.629Z",
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminBatchProductVariantRequest/page.mdx": "2024-12-09T13:21:34.309Z",
"references/types/WorkflowTypes/ProductWorkflow/interfaces/types.WorkflowTypes.ProductWorkflow.ExportProductsDTO/page.mdx": "2025-02-11T11:36:51.281Z",
"app/contribution-guidelines/admin-translations/page.mdx": "2024-11-14T08:54:15.369Z",
"app/integrations/guides/sanity/page.mdx": "2025-02-05T09:10:44.478Z",
"references/api_key/types/api_key.FindConfigOrder/page.mdx": "2024-11-25T17:49:28.715Z",
"references/auth/types/auth.FindConfigOrder/page.mdx": "2024-11-25T17:49:28.887Z",
www/apps/resources/generated/files-map.mjs
-12
View File
@@ -763,14 +763,6 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/commerce-modules/user/workflows/page.mdx",
"pathname": "/commerce-modules/user/workflows"
},
{
"filePath": "/www/apps/resources/app/contribution-guidelines/admin-translations/page.mdx",
"pathname": "/contribution-guidelines/admin-translations"
},
{
"filePath": "/www/apps/resources/app/contribution-guidelines/docs/page.mdx",
"pathname": "/contribution-guidelines/docs"
},
{
"filePath": "/www/apps/resources/app/create-medusa-app/page.mdx",
"pathname": "/create-medusa-app"
@@ -1267,10 +1259,6 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/troubleshooting/workflow-errors/page.mdx",
"pathname": "/troubleshooting/workflow-errors"
},
{
"filePath": "/www/apps/resources/app/usage/page.mdx",
"pathname": "/usage"
},
{
"filePath": "/www/apps/resources/references/api_key/IApiKeyModuleService/methods/api_key.IApiKeyModuleService.authenticate/page.mdx",
"pathname": "/references/api_key/IApiKeyModuleService/methods/api_key.IApiKeyModuleService.authenticate"
www/apps/resources/generated/sidebar.mjs
+8 -40
View File
@@ -7159,6 +7159,14 @@ export const generatedSidebar = [
"path": "https://docs.medusajs.com/resources/references/js-sdk/admin/claim",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "ref",
"title": "draftOrder",
"path": "https://docs.medusajs.com/resources/references/js-sdk/admin/draftOrder",
"children": []
},
{
"loaded": true,
"isPathHref": true,
@@ -25101,45 +25109,5 @@ export const generatedSidebar = [
]
}
]
},
{
"loaded": true,
"isPathHref": true,
"type": "category",
"title": "Other",
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "sub-category",
"title": "Contribution Guidelines",
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/contribution-guidelines/docs",
"title": "Docs",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/contribution-guidelines/admin-translations",
"title": "Admin Translations",
"children": []
}
]
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/usage",
"title": "Usage",
"children": []
}
]
}
]
www/apps/resources/next.config.mjs
+10
View File
@@ -133,6 +133,16 @@ const nextConfig = {
destination: "/recipes/erp",
permanent: true,
},
{
source: "/contribution-guidelines/:path",
destination: `${process.env.NEXT_PUBLIC_BASE_URL}/learn/resources/contribution-guidelines/:path`,
permanent: true,
},
{
source: "/usage",
destination: `${process.env.NEXT_PUBLIC_BASE_URL}/learn/resources/usage`,
permanent: true,
},
]
},
outputFileTracingExcludes: {
www/apps/resources/sidebar.mjs
-27
View File
@@ -212,31 +212,4 @@ export const sidebar = sidebarAttachHrefCommonOptions([
title: "References",
children: referencesSidebar,
},
{
type: "category",
title: "Other",
children: [
{
type: "sub-category",
title: "Contribution Guidelines",
children: [
{
type: "link",
path: "/contribution-guidelines/docs",
title: "Docs",
},
{
type: "link",
path: "/contribution-guidelines/admin-translations",
title: "Admin Translations",
},
],
},
{
type: "link",
path: "/usage",
title: "Usage",
},
],
},
])