Contributing to Documentation

Thank you for your interest in improving the CoCart API documentation! This guide will help you understand how to contribute effectively.

Overview

The CoCart API documentation is built with Mintlify, a modern documentation platform that uses MDX (Markdown + JSX) files and is hosted publicly on GitHub at cocart-headless/cocart-api-documentation.

Ways to Contribute

You can help improve the documentation in several ways:

Fix Typos & Errors

Correct spelling mistakes, grammar issues, or technical inaccuracies

Improve Clarity

Rewrite confusing sections to make them easier to understand

Add Examples

Contribute code examples in different programming languages

Write Tutorials

Create step-by-step guides for common use cases

Getting Started

Prerequisites

Before you begin, make sure you have:

A GitHub account
Git installed on your computer
Node.js (v18 or higher) installed
Basic familiarity with Markdown and Git workflows

Setting Up Your Development Environment

Fork the repository Visit the documentation repository and click the “Fork” button in the top-right corner.
Clone your fork

git clone https://github.com/YOUR-USERNAME/cocart-api-documentation.git
cd cocart-api-documentation

Install Mintlify CLI

npm install -g mintlify

Start the development server

mintlify dev

The documentation will be available at http://localhost:3000.

If mintlify dev isn’t working, try running mintlify install to reinstall dependencies.

Documentation Structure

Understanding the project structure will help you navigate and contribute effectively:

cocart-api-documentation/
├── docs.json                      # Navigation and site configuration
├── api-reference/                 # API endpoint documentation
│   ├── v1/                       # API v1 endpoints
│   ├── v2/                       # API v2 endpoints
│   └── jwt/                      # JWT authentication endpoints
├── documentation/                 # User guides and features
│   ├── developers/               # Developer resources
│   └── guides/                   # How-to guides
├── tutorials/                     # Step-by-step tutorials
├── getting-started/              # Setup and quick start guides
├── cli-reference/                # CLI command documentation
├── knowledge-base/               # FAQ and troubleshooting
└── resources/                    # Community and support info

Key Files

docs.json - Controls navigation, theme, and site settings
MDX files - Content pages using Markdown with React components
CLAUDE.md - Project-specific contribution guidelines

Writing Guidelines

Frontmatter Requirements

Every MDX file must include frontmatter with at least these fields:

---
title: "Clear, Descriptive Page Title"
description: "Concise summary for SEO and navigation (1-2 sentences)"
---

Optional frontmatter fields:

---
title: "Page Title"
sidebarTitle: "Shorter Sidebar Title"
description: "Page description"
icon: "icon-name"              # Font Awesome icon
tag: "NEW"                     # Badge: NEW, WIP, BETA, etc.
---

Writing Style

Follow these style guidelines for consistency:

Voice and Tone

Use second-person voice (“you”) when addressing the reader
Keep tone professional but friendly
Write in active voice
Be concise and direct

Good: “You can authenticate using Basic Auth or JWT tokens.”Bad: “Users are able to utilize either Basic Auth or JWT tokens for authentication purposes.”

Code Examples

Include code examples for all procedural content
Add language tags to all code blocks
Test all code examples before submitting
Include both basic and advanced use cases where appropriate
Show examples in multiple languages when possible (JavaScript, PHP, cURL)

const response = await fetch('https://example.com/wp-json/cocart/v2/cart');
const cart = await response.json();

Links and References

Use relative paths for internal links: [link text](/path/to/page)
Use descriptive link text (avoid “click here”)
Link to relevant sections for additional context

Good: See [Authentication](/api-reference/authentication) for more details.Bad: Click [here](https://docs.cocartapi.com/api-reference/authentication) for more information.

Structure

Start procedural content with prerequisites
Use clear headings to organize content
Include “What You’ll Learn” or “Overview” sections for tutorials
Add “Next Steps” or “What’s Next” sections where appropriate

Using Mintlify Components

Mintlify provides special components to enhance your documentation:

Callouts

Use callouts to highlight important information:

<Info>
  This is informational content that provides helpful context.
</Info>

<Warning>
  This warns users about potential issues or important considerations.
</Warning>

<Tip>
  This offers helpful tips or best practices.
</Tip>

<Note>
  This provides additional notes or clarifications.
</Note>

Cards

Create card layouts for organized content:

<CardGroup cols={2}>
  <Card title="Card Title" icon="icon-name" href="/link">
    Card description
  </Card>

  <Card title="Another Card" icon="icon-name" href="/link">
    Another description
  </Card>
</CardGroup>

Accordions

Use accordions for collapsible content:

<AccordionGroup>
  <Accordion title="Section Title">
    Content that can be expanded/collapsed
  </Accordion>

  <Accordion title="Another Section">
    More collapsible content
  </Accordion>
</AccordionGroup>

Code Groups

Show code in multiple languages using CodeGroup:

curl -X GET https://example.com/wp-json/cocart/v2/cart

For more components and options, see the Mintlify Components Documentation.

Contribution Workflow

Making Changes

Create a new branch
```
git checkout -b fix/improve-authentication-docs
```
Branch naming conventions:
- fix/short-description - Bug fixes or corrections
- add/short-description - New content
- refactor/short-description - Reorganizing content
- update/short-description - Updating existing content
Make your changes Edit MDX files in your preferred text editor. The local dev server will auto-reload as you make changes.
Preview your changes Check http://localhost:3000 to see how your changes look before committing.

Update navigation (if adding new pages) Add your new page to docs.json in the appropriate section:

{
  "group": "Tutorials",
  "pages": [
    "tutorials/existing-page",
    "tutorials/your-new-page"
  ]
}

Committing Changes

Follow these commit guidelines:

Write clear commit messages

Subject line: 50 characters or less, imperative mood
Body: Wrap at 72 characters, explain what and why
No period at end of subject line

git commit -m "Fix typo in authentication tutorial

Corrected the endpoint URL in the Basic Auth example.
The previous URL was missing the /wp-json prefix."

Never skip pre-commit hooks

The repository may have pre-commit hooks for validation. Never use --no-verify flag.

Commit frequently

Make small, atomic commits that each address one specific change.

Submitting Your Contribution

Push your branch to GitHub

git push origin fix/improve-authentication-docs

Create a Pull Request
- Go to your fork on GitHub
- Click “Compare & pull request”
- Fill out the PR template with:
  - Clear description of your changes
  - Why the changes are needed
  - Any related issues

Address review feedback Maintainers may request changes. Make updates to your branch and push again:

git add .
git commit -m "Address review feedback"
git push origin fix/improve-authentication-docs

Updating docs.json

The docs.json file controls navigation and site configuration. When updating it: The documentation has versioned navigation (stable and pre-release):

{
  "navigation": {
    "versions": [
      {
        "version": "stable",
        "default": true,
        "anchors": [...]
      },
      {
        "version": "pre-release",
        "anchors": [...]
      }
    ]
  }
}

Adding a New Page

When you add a new page, include it in the appropriate tab and group:

{
  "tab": "Tutorials",
  "groups": [
    {
      "group": "Tutorials",
      "pages": [
        "tutorials/existing-tutorial",
        "tutorials/your-new-tutorial"
      ]
    }
  ]
}

Always validate your JSON syntax. Invalid JSON will break the entire documentation site.

docs.json Schema

Refer to the Mintlify docs.json schema for complete configuration options.

Testing Your Changes

Before submitting a pull request:

Content Strategy

When contributing content, keep these principles in mind:

Just Enough

Document enough for user success - not too much, not too little

Accuracy First

Prioritize accuracy and usability over comprehensiveness

Evergreen Content

Write content that remains relevant over time when possible

Avoid Duplication

Search for existing info before adding new content

Common Mistakes to Avoid

Do NOT:

Skip frontmatter on any MDX file
Use absolute URLs for internal links
Include untested code examples
Make assumptions - ask for clarification instead
Use --no-verify when committing
Modify changelog files directly (these are maintained by the CoCart team)

Getting Help

Need help with your contribution?

Questions about content: Ask in the #documentation channel on Discord
Technical issues with Mintlify: Check the Mintlify documentation
Report documentation issues: Open an issue on GitHub

Recognition

Contributors are valued members of the CoCart community! Significant contributions may be recognized:

Listed in documentation contributors
Mentioned in release notes
Invited to join the documentation team

Resources

Mintlify Docs

Official Mintlify documentation

MDX Docs

Learn about MDX syntax

CoCart Community

Join our Discord community

GitHub Repo

Documentation repository

What’s Next?

Ready to contribute? Here are some good starting points:

Look for pages tagged with “WIP” (work in progress) that need completion or reviewing before finalization and tagging as “NEW”
Check the GitHub issues for documentation tasks
Review recent changes to understand current documentation priorities
Start with small improvements like fixing typos before tackling larger contributions

Thank you for helping make CoCart documentation better for everyone!

Overview

Getting Started

Features

Guides

Developers

Tools and Resources

Resources

​Overview

​Ways to Contribute

Fix Typos & Errors

Improve Clarity

Add Examples

Write Tutorials

​Getting Started

​Prerequisites

​Setting Up Your Development Environment

​Documentation Structure

​Key Files

​Writing Guidelines

​Frontmatter Requirements

​Writing Style

​Using Mintlify Components

​Callouts

​Cards

​Accordions

​Code Groups

​Contribution Workflow

​Making Changes

​Committing Changes

​Submitting Your Contribution

​Updating docs.json

​Navigation Structure

​Adding a New Page

​docs.json Schema

​Testing Your Changes

​Content Strategy

Just Enough

Accuracy First

Evergreen Content

Avoid Duplication

​Common Mistakes to Avoid

​Getting Help

​Recognition

​Resources

Mintlify Docs

MDX Docs

CoCart Community

GitHub Repo

​What’s Next?

Overview

Ways to Contribute

Getting Started

Prerequisites

Setting Up Your Development Environment

Documentation Structure

Key Files

Writing Guidelines

Frontmatter Requirements

Writing Style

Using Mintlify Components

Callouts

Cards

Accordions

Code Groups

Contribution Workflow

Making Changes

Committing Changes

Submitting Your Contribution

Updating docs.json

Navigation Structure

Adding a New Page

docs.json Schema

Testing Your Changes

Content Strategy

Common Mistakes to Avoid

Getting Help

Recognition

Resources

What’s Next?