Saleor Documentation

https://docs.saleor.io
Project homepage: https://saleor.io
Saleor Core source code: https://github.com/mirumee/saleor
Saleor Dashboard source code: https://github.com/mirumee/saleor-dashboard
Saleor Storefront source code: https://github.com/mirumee/saleor-storefront

What's In This Document

Get Started in 5 Minutes
Directory Structure
Editing Content
Adding Content
Full Documentation

Get Started in 5 Minutes

Make sure you are using Node in version 12+:

node --version

Install project dependencies:

npm install

Run your dev server:

npm start

Production Build

Build project:

npm run build

Testing build local:

npm run serve

Editing Content

Directory Structure

/docs/dashboard Current dashboard user documentation.
/docs/developer/api-reference Automatically generated API reference.
/docs/developer Current developer documentation.
/docusaurus.config.js Docusaurus configuration file.
/docusaurus2-graphql-doc-generator GraphQL API Reference plugin code.
/sidebars.js Sidebar menu structure.
/static Styling and other static files.
/versioned_docs Previous versions of documentation.

Formatting

Code formatting

Code and response examples should be inside code blocks with proper language:

```graphql
query{
  id
  name
}
```

```json
{
  "errorCode": 400
}
```

Lining pages

Use full path to the file to avoid linking to wrong page.

✅ Example of good link: [Attributes](/docs/developer/attributes.mdx)
🛑 Avoid: [Attributes](/attributes)

Using custom React components

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-products.mdx file -->
---
title: Exporting Products
---

import Chart from "@site/components/Chart";

...

<Chart
  definition={`
  graph TD
    D[Export products data <br> Background Worker] -->|Success| E[Send email to user <br> with a link to <br> download file]
    D -->|Success| X[Set SUCCESS <br>ExportFile status]
    E -->Y[Create export file <br>sent event]
    X -->F[Create data export <br>success event]
    D -->|Failed| G[Set FAILED <br>ExportFile status]
    G --> U[Create data export <br>failed event]
    U --> J[Send email to the user<br>with information <br>about failing export]
    J --> K[Create export failed <br>info sent event]
`}
/>

For charts we are using Mermaid package.

Editing an existing docs page

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

Adding Content

Adding a new docs page to an existing sidebar

Create the doc as a new markdown file in /docs, example docs/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 sidebar.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

Adding items to your site's top navigation bar

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

Adding custom pages

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.js to add to the headerLinks element:

{
  headerLinks: [
    ...
    { page: 'my-new-custom-page', label: 'My New Custom Page' },
    ...
  ],
  ...
}

For more information about custom pages, click here.

Updating the API Reference

All files in /docs/api-reference are generated by @edno/docusaurus2-graphql-doc-generator script. Introduction page is automatically copied from /docs/api-introduction.mdx file.

To update the API reference:

Start Saleor API at http://localhost:8000
Run npm run update-api-reference

Debugging

In dev mode, Docusaurus serves a debug page with a list of all available routes and config at http://localhost:3000/__docusaurus/debug.

Style

Available visual components and text formatting can be found at http://localhost:3000/docs/3.0/style-guide.

Full Docusaurus Documentation

Full documentation can be found on the website.

chronark / saleor-docs Goto Github PK

saleor-docs's Introduction