contribute

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contributing to Trellis

为Trellis做贡献

Contributions are split across two repos:

What	Repo	Purpose
Documentation pages	mindfold-ai/docs	Mintlify doc site
Skills + Spec templates	mindfold-ai/Trellis	`marketplace/` directory

贡献内容分为两个仓库进行：

内容类型	仓库	用途
文档页面	mindfold-ai/docs	Mintlify文档站点
Skill + 规范模板	mindfold-ai/Trellis	`marketplace/` 目录

Docs Repo 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

docs/
├── docs.json              # 导航配置（新增页面必须更新）
│
├── index.mdx              # 英文首页
├── quickstart.mdx         # 英文快速开始
├── zh/index.mdx           # 中文首页
├── zh/quickstart.mdx      # 中文快速开始
│
├── guides/                # 英文指南页面
├── zh/guides/             # 中文指南页面
│
├── templates/             # 英文模板页面
├── zh/templates/          # 中文模板页面
│
├── skills-market/         # 英文Skill市场页面
├── zh/skills-market/      # 中文Skill市场页面
│
├── blog/                  # 英文技术博客
├── zh/blog/               # 中文技术博客
│
├── changelog/             # 英文更新日志
├── zh/changelog/          # 中文更新日志
│
├── contribute/            # 英文贡献指南
├── zh/contribute/         # 中文贡献指南
│
├── showcase/              # 英文案例展示
└── zh/showcase/           # 中文案例展示

Trellis Main Repo Marketplace Structure

Trellis主仓库市场结构

marketplace/
├── index.json             # Template registry (lists all available templates)
├── README.md              # Marketplace overview
├── specs/                 # Spec templates
│   └── electron-fullstack/
│       ├── README.md
│       ├── frontend/
│       ├── backend/
│       ├── guides/
│       └── shared/
└── skills/                # Skills
    └── trellis-meta/
        ├── SKILL.md
        └── references/

marketplace/
├── index.json             # 模板注册表（列出所有可用模板）
├── README.md              # 市场概览
├── specs/                 # 规范模板
│   └── electron-fullstack/
│       ├── README.md
│       ├── frontend/
│       ├── backend/
│       ├── guides/
│       └── shared/
└── skills/                # Skill
    └── trellis-meta/
        ├── SKILL.md
        └── references/

Understanding docs.json

理解docs.json

The navigation uses a language-based structure:

json

{
  "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

导航采用基于语言的结构：

json

{
  "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": [
          // 结构相同，路径带zh/前缀
        ]
      }
    ]
  }
}

关键点：

英文页面：无前缀（例如：
```
guides/specs
```
）
中文页面：带
```
zh/
```
前缀（例如：
```
zh/guides/specs
```
）
支持嵌套分组（例如：资源市场下的Skill）
```
expanded: false
```
表示分组默认折叠

Contributing a Spec Template

贡献规范模板

Spec templates live in the Trellis main repo at

marketplace/specs/

规范模板存放在Trellis主仓库的

marketplace/specs/

目录下。

1. Create template directory

1. 创建模板目录

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.

marketplace/specs/your-template-name/
├── README.md              # 模板概览（必填）
├── frontend/              # 前端指南
│   ├── index.md
│   └── ...
├── backend/               # 后端指南
│   ├── index.md
│   └── ...
├── guides/                # 思路指南
│   └── ...
└── shared/                # 跨领域内容（可选）
    └── ...

目录结构可根据技术栈调整，仅保留与模板相关的目录即可。

2. Register in index.json

2. 在index.json中注册

Add your template to

marketplace/index.json

in the Trellis repo:

json

{
  "id": "your-template-id",
  "type": "spec",
  "name": "Your Template Name",
  "description": "Brief description of the template",
  "path": "marketplace/specs/your-template-name",
  "tags": ["relevant", "tags"]
}

在Trellis仓库的

marketplace/index.json

中添加你的模板：

json

{
  "id": "your-template-id",
  "type": "spec",
  "name": "Your Template Name",
  "description": "Brief description of the template",
  "path": "marketplace/specs/your-template-name",
  "tags": ["relevant", "tags"]
}

3. Create documentation pages (both languages, in docs repo)

3. 创建文档页面（双语，在文档仓库中）

English:

templates/specs-your-template.mdx

Chinese:

zh/templates/specs-your-template.mdx

Use this frontmatter:

yaml

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

英文：

templates/specs-your-template.mdx

中文：

zh/templates/specs-your-template.mdx

使用如下页头配置：

yaml

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

4. Update navigation in docs.json

4. 更新docs.json中的导航

Find the

Spec Templates

nested group and add your page:

json

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

Do the same for Chinese under

"language": "zh"

json

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

找到

Spec Templates

嵌套分组，添加你的页面：

json

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

在

"language": "zh"

下的中文导航中执行相同操作：

json

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

5. Update the overview page

5. 更新概览页面

Add your template to the table in:

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

在以下文件的表格中添加你的模板：

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

Contributing a Skill

贡献Skill

Skills live in the Trellis main repo at

marketplace/skills/

Skill存放在Trellis主仓库的

marketplace/skills/

目录下。

1. Create skill directory

1. 创建Skill目录

marketplace/skills/your-skill/
├── SKILL.md               # Skill definition (required)
└── references/            # Reference docs (optional)

See Claude Code Skills documentation for SKILL.md format.

marketplace/skills/your-skill/
├── SKILL.md               # Skill定义（必填）
└── references/            # 参考文档（可选）

SKILL.md的格式请参考Claude Code Skills文档。

2. Register in index.json

2. 在index.json中注册

Add your skill to

marketplace/index.json

in the Trellis repo:

json

{
  "id": "your-skill-id",
  "type": "skill",
  "name": "Your Skill Name",
  "description": "Brief description",
  "path": "marketplace/skills/your-skill",
  "tags": ["relevant", "tags"]
}

在Trellis仓库的

marketplace/index.json

中添加你的Skill：

json

{
  "id": "your-skill-id",
  "type": "skill",
  "name": "Your Skill Name",
  "description": "Brief description",
  "path": "marketplace/skills/your-skill",
  "tags": ["relevant", "tags"]
}

3. Create documentation pages (in docs repo)

3. 创建文档页面（在文档仓库中）

English:

skills-market/your-skill.mdx

Chinese:

zh/skills-market/your-skill.mdx

英文：

skills-market/your-skill.mdx

中文：

zh/skills-market/your-skill.mdx

4. Update navigation in docs.json

4. 更新docs.json中的导航

Find the

Skills

nested group and add your page to both languages.

找到

Skills

嵌套分组，在双语导航中都添加你的页面。

5. Update the overview page

5. 更新概览页面

Add your skill to the table in:

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

在以下文件的表格中添加你的Skill：

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

Installation

安装方式

Users install skills via:

bash

npx skills add mindfold-ai/Trellis/marketplace -s your-skill

用户可通过以下命令安装Skill：

bash

npx skills add mindfold-ai/Trellis/marketplace -s your-skill

Contributing a Showcase Project

贡献案例展示项目

1. Copy the template

1. 复制模板

bash

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

bash

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

2. Fill in project details

2. 填写项目详情

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

更新
```
sidebarTitle
```
为你的项目名称
添加项目描述
将GitHub OG图片URL替换为你的仓库地址
描述你如何使用Trellis

3. Update navigation in docs.json

3. 更新docs.json中的导航

Find the

Showcase

项目展示

group and add your page:

json

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

Do the same for Chinese.

找到

Showcase

项目展示

分组，添加你的页面：

json

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

在中文导航中执行相同操作。

4. Add Card to overview page

4. 在概览页面添加卡片

Add a Card component to display your project:

English (

showcase/index.mdx

mdx

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

Chinese (

zh/showcase/index.mdx

mdx

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

添加Card组件展示你的项目：

英文（

showcase/index.mdx

）：

mdx

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

中文（

zh/showcase/index.mdx

）：

mdx

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

Contributing Documentation

贡献文档

Adding a new guide

添加新指南

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

在
```
guides/your-guide.mdx
```
创建页面
在
```
zh/guides/your-guide.mdx
```
创建中文版本
更新
```
docs.json
```
- 在双语的
```
Guides
```
分组中添加页面

Adding a blog post

添加博客文章

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

在
```
blog/your-post.mdx
```
创建页面
在
```
zh/blog/your-post.mdx
```
创建中文版本
更新
```
docs.json
```
- 在双语的
```
Tech Blog
```
分组中添加页面

Updating existing pages

更新现有页面

Find the file in the appropriate directory
Make your changes
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`

所有面向用户的内容必须同时提供英文和中文版本。

内容类型	英文路径	中文路径
首页	`index.mdx`	`zh/index.mdx`
指南	`guides/*.mdx`	`zh/guides/*.mdx`
模板	`templates/*.mdx`	`zh/templates/*.mdx`
Skill	`skills-market/*.mdx`	`zh/skills-market/*.mdx`
案例展示	`showcase/*.mdx`	`zh/showcase/*.mdx`
博客	`blog/*.mdx`	`zh/blog/*.mdx`
更新日志	`changelog/*.mdx`	`zh/changelog/*.mdx`

Development Setup

开发环境搭建

bash

undefined

bash

undefined

Install dependencies

安装依赖

pnpm install

Start local dev server

启动本地开发服务器

pnpm dev

Check markdown lint

检查Markdown语法

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

pnpm format


**提交前钩子**：项目使用husky配合lint-staged。提交代码时：

- Markdown文件会自动进行语法检查和格式化
- `verify-docs.py`会检查docs.json和页头配置

MDX Components

MDX组件

Mintlify supports MDX components. Common ones:

mdx

<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.

Mintlify支持MDX组件，常用组件如下：

mdx

<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>

允许使用内联HTML（MDX特性）。所有组件请参考Mintlify文档。

Submitting a PR

提交PR

For documentation changes (docs repo):

Fork:
```
https://github.com/mindfold-ai/docs
```

Clone:

git clone https://github.com/YOUR_USERNAME/docs.git

Install:
```
pnpm install
```
Branch:
```
git checkout -b feat/your-contribution
```
Make changes following this guide
Test:
```
pnpm dev
```
Commit with conventional message (e.g.,
```
docs: add xxx template
```
)
Push and create PR

For skills/spec templates (Trellis repo):

Fork:
```
https://github.com/mindfold-ai/Trellis
```

Clone:

git clone https://github.com/YOUR_USERNAME/Trellis.git

Add your skill/template under
```
marketplace/
```
Update
```
marketplace/index.json
```
Push and create PR

文档变更（文档仓库）：

Fork仓库：
```
https://github.com/mindfold-ai/docs
```

克隆到本地：

git clone https://github.com/YOUR_USERNAME/docs.git

安装依赖：
```
pnpm install
```
创建分支：
```
git checkout -b feat/your-contribution
```
按照本指南进行修改
测试：
```
pnpm dev
```
使用规范的提交信息（例如：
```
docs: add xxx template
```
）
推送代码并创建PR

Skill/规范模板变更（Trellis仓库）：

Fork仓库：
```
https://github.com/mindfold-ai/Trellis
```

克隆到本地：

git clone https://github.com/YOUR_USERNAME/Trellis.git

在
```
marketplace/
```
下添加你的Skill/模板
更新
```
marketplace/index.json
```
推送代码并创建PR

Checklist Before PR

PR提交前检查清单

Both EN and ZH versions created (for doc pages)
```
docs.json
```
updated for both languages (for doc pages)
```
marketplace/index.json
```
updated (for skills/templates)
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)

已创建英文和中文版本（文档页面）
已更新双语的
```
docs.json
```
配置（文档页面）
已更新
```
marketplace/index.json
```
配置（Skill/模板）
已在概览/索引页面添加新条目
已通过本地预览测试（
```
pnpm dev
```
）
无失效链接
代码块使用了正确的语言标签
页头包含标题和描述
图片已放置在
```
images/
```
目录中（如有）