Contributing to Trellis Docs

This skill guides you through contributing to the Trellis documentation project.

Project Structure

docs/
├── docs.json              # Navigation config (MUST update for new pages)
│
├── index.mdx              # English homepage
├── quickstart.mdx         # English quickstart
├── zh/index.mdx           # Chinese homepage
├── zh/quickstart.mdx      # Chinese quickstart
│
├── guides/                # English guide pages
├── zh/guides/             # Chinese guide pages
│
├── templates/             # English template pages
├── zh/templates/          # Chinese template pages
│
├── skills-market/         # English skill marketplace pages
├── zh/skills-market/      # Chinese skill marketplace pages
│
├── blog/                  # English tech blog
├── zh/blog/               # Chinese tech blog
│
├── changelog/             # English changelog
├── zh/changelog/          # Chinese changelog
│
├── contribute/            # English contribution guide
├── zh/contribute/         # Chinese contribution guide
│
├── showcase/              # English showcase
├── zh/showcase/           # Chinese showcase
│
├── plugins/               # Claude Code plugins (one plugin per skill)
│   └── trellis-meta/
│       ├── plugin.json
│       └── skills/trellis-meta/
│           └── SKILL.md
│
└── marketplace/           # Other downloadable assets
    └── specs/             # Spec template directories

Note: Plugin skills follow Claude Code plugin structure. Content in marketplace/ is excluded from Mintlify rendering.

Understanding docs.json

The navigation uses a language-based structure:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart"]
          },
          {
            "group": "Guides",
            "pages": ["guides/specs", "guides/tasks", ...]
          },
          {
            "group": "Resource Marketplace",
            "pages": [
              {
                "group": "Skills",
                "expanded": false,
                "pages": ["skills-market/index", "skills-market/trellis-meta"]
              },
              {
                "group": "Spec Templates",
                "expanded": false,
                "pages": ["templates/specs-index", "templates/specs-electron"]
              }
            ]
          }
        ]
      },
      {
        "language": "zh",
        "groups": [
          // Same structure with zh/ prefix
        ]
      }
    ]
  }
}

Key points:

• English pages: no prefix (e.g., guides/specs)
• Chinese pages: zh/ prefix (e.g., zh/guides/specs)
• Nested groups supported (e.g., Skills inside Resource Marketplace)
• expanded: false keeps groups collapsed by default

Contributing a Spec Template

1. Create template directory

marketplace/specs/your-template-name/
├── README.md              # Template overview (required)
├── frontend/              # Frontend guidelines
│   ├── index.md
│   └── ...
├── backend/               # Backend guidelines
│   ├── index.md
│   └── ...
├── guides/                # Thinking guides
│   └── ...
└── shared/                # Cross-cutting concerns (optional)
    └── ...

Structure varies by stack. Include directories relevant to your template.

2. Create documentation pages (both languages)

English: templates/specs-your-template.mdx Chinese: zh/templates/specs-your-template.mdx

Use this frontmatter:

---
title: 'Your Template Name'
description: 'Brief description'
---

3. Update navigation in docs.json

Find the Spec Templates nested group and add your page:

{
  "group": "Spec Templates",
  "expanded": false,
  "pages": ["templates/specs-index", "templates/specs-electron", "templates/specs-your-template"]
}

Do the same for Chinese under "language": "zh":

{
  "group": "Spec Templates",
  "expanded": false,
  "pages": [
    "zh/templates/specs-index",
    "zh/templates/specs-electron",
    "zh/templates/specs-your-template"
  ]
}

4. Update the overview page

Add your template to the table in:

• templates/specs-index.mdx
• zh/templates/specs-index.mdx

Contributing a Skill

1. Create plugin directory

plugins/your-plugin/
├── plugin.json            # Plugin manifest
└── skills/
    └── your-skill/
        ├── SKILL.md       # Skill definition (required)
        └── references/    # Reference docs (optional)

2. Create plugin.json

{
  "name": "your-plugin",
  "version": "1.0.0",
  "description": "Your plugin description",
  "author": { "name": "Your Name" },
  "skills": ["./skills/"]
}

3. Register in marketplace.json

Add your plugin to .claude-plugin/marketplace.json:

{
  "plugins": [
    {
      "name": "your-plugin",
      "source": "./plugins/your-plugin",
      "description": "Your plugin description"
    }
  ]
}

4. Create documentation pages

English: skills-market/your-skill.mdx Chinese: zh/skills-market/your-skill.mdx

5. Update navigation in docs.json

Find the Skills nested group and add your page to both languages.

6. Update the overview page

Add your skill to the table in:

• skills-market/index.mdx
• zh/skills-market/index.mdx

Contributing a Showcase Project

1. Copy the template

cp showcase/template.mdx showcase/your-project.mdx
cp zh/showcase/template.mdx zh/showcase/your-project.mdx

2. Fill in project details

• Update sidebarTitle with your project name
• Add project description
• Replace GitHub OG image URL with your repo
• Describe how you used Trellis

3. Update navigation in docs.json

Find the Showcase / 项目展示 group and add your page:

{
  "group": "Showcase",
  "expanded": false,
  "pages": ["showcase/index", "showcase/open-typeless", "showcase/your-project"]
}

Do the same for Chinese.

4. Add Card to overview page

Add a Card component to display your project:

English (showcase/index.mdx):

<Card title="Project Name" icon="icon-name" href="/showcase/your-project">
  One-line description
</Card>

Chinese (zh/showcase/index.mdx):

<Card title="项目名" icon="icon-name" href="/zh/showcase/your-project">
  一句话描述
</Card>

Contributing Documentation

Adding a new guide

1. Create the page in guides/your-guide.mdx
2. Create Chinese version in zh/guides/your-guide.mdx
3. Update docs.json - add to Guides group in both languages

Adding a blog post

1. Create the page in blog/your-post.mdx
2. Create Chinese version in zh/blog/your-post.mdx
3. Update docs.json - add to Tech Blog group in both languages

Updating existing pages

1. Find the file in the appropriate directory
2. Make your changes
3. Ensure both language versions stay in sync

Bilingual Requirements

All user-facing content must have both English and Chinese versions.

Content Type	English Path	Chinese Path
Homepage	index.mdx	zh/index.mdx
Guides	guides/*.mdx	zh/guides/*.mdx
Templates	templates/*.mdx	zh/templates/*.mdx
Skills	skills-market/*.mdx	zh/skills-market/*.mdx
Showcase	showcase/*.mdx	zh/showcase/*.mdx
Blog	blog/*.mdx	zh/blog/*.mdx
Changelog	changelog/*.mdx	zh/changelog/*.mdx

Development Setup

# Install dependencies
pnpm install

# Start local dev server
pnpm dev

# Check markdown lint
pnpm lint:md

# Verify docs structure
pnpm verify

# Format files
pnpm format

Pre-commit hooks: The project uses husky with lint-staged. On commit:

• Markdown files are auto-linted and formatted
• verify-docs.py checks docs.json and frontmatter

MDX Components

Mintlify supports MDX components. Common ones:

<Card title="Title" icon="download" href="/path">
  Card content here
</Card>

<CardGroup cols={2}>
  <Card>...</Card>
  <Card>...</Card>
</CardGroup>

<Accordion title="Click to expand">Hidden content</Accordion>

<AccordionGroup>
  <Accordion>...</Accordion>
</AccordionGroup>

Inline HTML is allowed (MDX). See Mintlify docs for all components.

Submitting a PR

1. Fork the repo on GitHub: https://github.com/mindfold-ai/docs
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/docs.git
3. Install dependencies: pnpm install
4. Create a branch: git checkout -b feat/your-contribution
5. Make changes following this guide
6. Test locally: pnpm dev
7. Commit with conventional message (e.g., docs: add xxx template)
8. Push to your fork and create PR to original repo's main branch

Checklist Before PR

• Both EN and ZH versions created
• docs.json updated for both languages
• Overview/index pages updated with new entries
• Local preview tested (pnpm dev)
• No broken links
• Code blocks have correct language tags
• Frontmatter includes title and description
• Images placed in images/ directory (if any)