Contributing technical documentation

Thanks for helping improve WooCommerce's developer documentation. Our docs are powered by Docusaurus, and live inside the woocommerce/docs/ folder of the monorepo.

このガイドでは、効果的に貢献するための仕組み、ツール、プロセスについて説明します。

Getting started

This guide presumes that you're familiar with basic Git and GitHub functionality, that you're signed into a GitHub account, and that you have Git setup locally. If you're new to GitHub, we recommend reading their quickstart and working with forks guides before getting started.

Initial setup

1. Fork the WooCommerce monorepo on GitHub. If asked, you can safely check the copy the trunk branch only option.
2. Clone the fork that you just created. This will allow you to edit it locally.

Making changes

1. Prior to making any changes, ensure your trunk branch is up to date with the monorepo's trunk by syncing it.

2. For each modification you'd like to make, create a new branch off trunk in your fork that starts with docs/. For example, if you're adding a doc about improving extension performance, you could call your branch docs/improve-extension-performance.

3. Create or edit markdown files inside the appropriate folder under docs/.

4. If needed, update the folder's _category_.json (for sidebar label/position).

5. Run a build to verify changes, confirm that the sitemaps and llms-txt files are updated, and detect markdown linting errors and broken links (link checking only happens on build):

   npm run build
   

Opening a pull request

1. Commit and push your changes to your fork.
2. Open a pull request to woocommerce/woocommerce, targeting the trunk branch.
3. Use a descriptive title, and fill out the PR template. Include:
   • Rationale for new files or categories
   • A note about any sidebar or structure changes
4. The WooCommerce Developer Advocacy team will review and merge your changes.

Docs folder anatomy

Tooling and configuration

• Supporting tooling and config lives in:
  • woocommerce/docs/_docu-tools/
• Top-level sidebar and navbar are configured in:
  • sidebars.ts
  • docusaurus.config.ts

Documentation files

• Docs location: All documentation lives inside of woocommerce/docs/

• Each folder is sidebar or top nav category, for example: getting-started, code-snippets, etc.

• Sidebar configuration for each category is managed using a _category_.json file inside each category folder:

  {
      "position": 7,
      "label": "Code snippets"
  }
  

Adding images

ドキュメントの画像はすべて

docs/_docu-tools/static/img/doc_images/

マークダウン・ファイルに画像を含めるには、次のように参照する：

![Alt text](/img/doc_images/your-image-name.png)

Creating New Categories

新しいカテゴリーを作成する前に、本当に必要かどうかを検討する必要があります。可能であれば、既存のカテゴリーでコンテンツを作成するのがデフォルトです。新しいカテゴリーを作成する必要がある場合は、以下の手順に従ってください：

1. Inside the /docs folder, create a sub-folder with a descriptive name. For example, if you wanted to create a Checkout design guidelines section, you'd create a folder called /docs/checkout-design-guidelines.

2. Create a _category_.json file inside each category folder and give it a position it should have in the sidebar as well as a label:

   {
       "position": 10,
       "label": "Checkout design guidelines"
   }
   

新しいカテゴリーを作成する際は、プルリクエストの説明文にカテゴリーを作成した理由についての根拠を含めてください。

Writing guidelines and references

• Use short, URL-friendly file names (kebab-case, no spaces)
• Avoid pasting from rich text editors like Google Docs, which may introduce invalid characters
• Check our docs style guide for detailed writing guidelines
• Reference the Docusaurus documentation for additional guidance