- Documentation: https://docs.saleor.io
- Project homepage: https://saleor.io
- Saleor Core source code: https://github.com/saleor/saleor
- Saleor Dashboard source code: https://github.com/saleor/saleor-dashboard
- Saleor React Storefront source code: https://github.com/saleor/react-storefront
Note
- This requires docker or equivalent software to be installed and running on the machine.
- Other editors than VSCode are supported: see the official documentation
Usage:
- Install the Dev Containers extension for VSCode
- Press F1 then run the command:
>dev containers: rebuild and Reopen in Container - Once started, it should open a new VSCode workspace which should allow you to perform remote coding (against the container)
- Go to
http://127.0.0.1:5000/(may take up to a minute to load when opened for the first time) - When editing the code in VSCode, changes will reflect at
http://127.0.0.1:5000/(may take a few seconds)
More details are available in the official VSCode documentation: https://code.visualstudio.com/docs/devcontainers/containers#_getting-started
Steps:
- Go under
.devcontainer/folder - Run:
docker-compose up
- Visit
http://127.0.0.1:5000/(may take up to a minute to load when opened for the first time) - Any changes made to the files will reflect at
http://127.0.0.1:5000/(may take a few seconds)
- Make sure you are using Node in version 20+:
node --version- Install project dependencies:
npm install- Run your dev server:
npm start- Build project:
npm run build- Testing build local:
npm run serve/docsMain docs content directory./docs/api-referenceAPI reference generated from schema.graphql/docusaurus.config.jsDocusaurus configuration file./docusaurus2-graphql-doc-generatorGraphQL API Reference plugin code./sidebars.jsSidebar menu structure./staticStyling and other static files.
Code and response examples should be inside code blocks with proper language:
```graphql
query {
id
name
}
``````json
{
"errorCode": 400
}
```Use full path to the file to avoid linking to wrong page.
- âś… Example of good link:
[Attributes](/docs/developer/attributes.mdx) - 🛑 Avoid:
[Attributes](/attributes)
All documentation files use extension:
.mdx- Developer documentation.md- Dashboard documentation
If your page uses custom react components, you are required to use .mdx file extension. Import statement is also required:
## <!-- /docs/developer/export/export-overview.mdx file -->
## title: Exporting Products
import Foo from "@site/components/Foo";
...
<Foo />For charts we are using Mermaid package.
Edit docs by navigating to docs/ and editing the corresponding document:
docs/doc-to-be-edited.md
---
id: page-needs-edit
title: This Doc Needs To Be Edited
---
Edit me...For more information about docs, click here
- Create the doc as a new markdown file in
/docs, exampledocs/newly-created-doc.md:
---
id: newly-created-doc
title: This Doc Needs To Be Edited
---
My new content here..- Refer to that doc's ID in an existing sidebar in
sidebars.js:
// Add newly-created-doc to the Getting Started category of docs
{
"docs": {
"Getting Started": [
"quick-start",
"newly-created-doc" // new doc here
],
...
},
...
}For more information about adding new docs, click here
- Add links to docs, custom pages or external links by editing the headerLinks field of
siteConfig.js:
{
headerLinks: [
...
/* you can add docs */
{
type: "doc",
docId: "dashboard/before-you-start",
label: "Dashboard Manual",
position: "left",
},
/* you can add custom pages */
{ page: 'help', label: 'Help' },
/* you can add external links */
{ href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
...
],
...
}For more information about the navigation bar, click here
- Docusaurus uses React components to build pages. The components are saved as .js files in
./pages/en: - If you want your page to show up in your navigation header, you will need to update
siteConfig.jsto add to theheaderLinkselement:
{
headerLinks: [
...
{ page: 'my-new-custom-page', label: 'My New Custom Page' },
...
],
...
}For more information about custom pages, click here.
Files in /docs/api-reference folder are generated by @graphql-markdown/docusaurus package. The introduction page is automatically copied from the /template/api-reference.mdx file.
To update the API reference:
- Get
schema.graphqllocally into the root of the saleor-docs repository by runningcurl -O https://raw.githubusercontent.com/saleor/saleor/refs/heads/main/saleor/graphql/schema.graphql - Run
npm run update-api-reference
The script behind the scenes does several steps:
- The api-reference is generated in
.tmpfolder. - The highlighting script makes additional improvements in the generated docs. It makes the Saleor version and required permissions more visible.
- The current references from
docsfolder are being removed and generated references in.tmpfolder are moved to thedocs. - The code examples are being injected. The code examples from the
examplesfolder are being put into corresponding files in the references folder.
Tip: To enable autocomplete in VSCode open docs folder in the workspace.
- Use only absolute paths, which is easier to maintain when moving files around or requires global search and replace.
- Use the
.mdxextension. - Start paths with
/. - Don't use
/docsas root path.
Don't:
[Attributes](developer/attributes.mdx)
[Attributes](/developer/attributes)
[Attributes](../../attributes)
[Attributes](/docs/developer/attributes)
Do:
[Attributes](/developer/attributes.mdx)
Saleor Docs are using Algolia DocSearch for the website search.
DocSearch crawls the website once a week on Friday and aggregates all the content in an Algolia index. This content is then queried directly from the front-end using the Algolia API.
The website's search results are meticulously ranked to enhance user relevance and experience. A custom ranking function, known as pageRank, is employed for this purpose. The ranking strategy prioritizes various content categories as follows:
-
metaPageRank: This takes precedence and is determined by a custom meta attribute, providing a top-tier ranking for specific content. -
Documentation Pages: General documentation pages are next in line for ranking, excluding those generated based on schema API reference and API storefront. -
API Reference Pages: These pages are ranked differently based on the type of operation they represent.
function pageRank(url) {
if (metaPageRank) {
return metaPageRank;
}
if (!/\/api-reference\//.test(url.pathname)) {
// not part of API reference
return "40";
}
if (/\/mutations\//.test(url.pathname)) {
// mutation
return "30";
}
if (/\/queries\//.test(url.pathname)) {
// query
return "20";
}
return "10";
}
For even finer control over search result rankings, you can manually influence the ranking of specified pages by adding a custom meta attribute - rank - to the page. The rank meta is configured to have the highest priority in Algolia.
To assign a custom rank to a particular page, use the following code snippet:
<head>
<meta name="rank" content="50" />
</head>
The main branch is automatically released to docs.saleor.io, which is handled by Vercel.
Run npm run lint to check for any linting errors on staged (modified) files.
Note that capitalization rules don't work well with front matter so you can ignore error messages located in the top --- section.
In dev mode, Docusaurus serves a debug page with a list of all available routes and config at http://localhost:3000/\_\_docusaurus/debug.
Full documentation can be found on the website.
Create settings.json under .vscode folder with:
{
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "always"
},
"eslint.debug": true,
"eslint.options": {
"extensions": [".js", ".jsx", ".md", ".mdx", ".ts", ".tsx"]
},
"eslint.runtime": "node",
"eslint.validate": [
"javascript",
"javascriptreact",
"typescript",
"typescriptreact",
"markdown",
"mdx"
],
"editor.formatOnSave": true
}