contribute

Name: contribute
Author: mindfold-ai

github.com/mindfold-ai开发15.0k110 次安装4 周前更新

代码仓库

关于 contribute

这是 Trellis 及其文档仓库的贡献指南，说明如何添加技能、规格模板、文档和项目展示页面，并涵盖注册、导航更新、本地化及 PR 检查。

主要功能

01文档贡献步骤
02技能与模板登记
03导航和索引更新
04中英文页面要求
05本地预览与 lint 检查
06PR 提交前检查清单

适用场景

01向 Trellis 添加技能
02发布规格模板
03创建双语文档页面
04准备贡献拉取请求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mindfold-ai/trellis --skill contribute

安装后在 Claude Code 中输入/contribute确认已加载。

详细介绍

为 Trellis 做贡献

贡献内容分布在两个仓库中：

内容	仓库	用途
文档页面	mindfold-ai/docs	Mintlify 文档站点
Skills + Spec 模板	mindfold-ai/Trellis	`marketplace/` 目录

文档仓库结构

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

Trellis 主仓库 Marketplace 结构

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/

了解 docs.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
        ]
      }
    ]
  }
}

要点：

英文页面：无前缀（例如，guides/specs）
中文页面：使用 zh/ 前缀（例如，zh/guides/specs）
支持嵌套分组（例如，Resource Marketplace 内的 Skills）
expanded: false 会使分组默认处于折叠状态

为 Spec 模板做贡献

Spec 模板位于 Trellis 主仓库的 marketplace/specs/ 中。

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)
    └── ...

目录结构因技术栈而异。请包含与模板相关的目录。

2. 在 index.json 中注册

在 Trellis 仓库的 marketplace/index.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. 创建文档页面（在文档仓库中创建两种语言版本）

英文：templates/specs-your-template.mdx 中文：zh/templates/specs-your-template.mdx

使用以下 frontmatter：

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

4. 在 docs.json 中更新导航

找到 Spec Templates 嵌套分组并添加页面：

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

对 "language": "zh" 下的中文页面执行相同操作：

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

5. 更新概览页面

将模板添加到以下页面的表格中：

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

为 Skill 做贡献

Skill 位于 Trellis 主仓库的 marketplace/skills/ 中。

1. 创建 Skill 目录

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

SKILL.md 格式请参阅 Codex Skills 文档。

2. 在 index.json 中注册

在 Trellis 仓库的 marketplace/index.json 中添加 Skill：

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

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

英文：skills-market/your-skill.mdx 中文：zh/skills-market/your-skill.mdx

4. 在 docs.json 中更新导航

找到 Skills 嵌套分组，并为两种语言添加页面。

5. 更新概览页面

将 Skill 添加到以下页面的表格中：

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

安装

用户通过以下方式安装 Skills：

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

为 Showcase 项目做贡献

1. 复制模板

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

2. 填写项目信息

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

3. 在 docs.json 中更新导航

找到 Showcase / 项目展示 分组并添加页面：

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

对中文页面执行相同操作。

4. 在概览页面中添加 Card

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

英文（showcase/index.mdx）：

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

中文（zh/showcase/index.mdx）：

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

为文档做贡献

添加新指南

在 guides/your-guide.mdx 中创建页面
在 zh/guides/your-guide.mdx 中创建中文版
更新 docs.json —— 将页面添加到两种语言的 Guides 分组中

添加博客文章

在 blog/your-post.mdx 中创建页面
在 zh/blog/your-post.mdx 中创建中文版
更新 docs.json —— 将页面添加到两种语言的 Tech Blog 分组中

更新现有页面

在相应目录中找到文件
进行修改
确保两种语言的版本保持同步

双语要求

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

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

开发环境配置

# 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

提交前钩子：项目使用 husky 和 lint-staged。提交时：

自动检查并格式化 Markdown 文件
verify-docs.py 检查 docs.json 和 frontmatter

MDX 组件

Mintlify 支持 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 文档。

提交 PR

文档变更（docs 仓库）：

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

技能／规范模板（Trellis 仓库）：

Fork：https://github.com/mindfold-ai/Trellis
克隆：git clone https://github.com/YOUR_USERNAME/Trellis.git
在 marketplace/ 下添加技能／模板
更新 marketplace/index.json
推送并创建 PR

提交 PR 前的检查清单

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

支持 Markdown

登录后评论

基本信息

作者: mindfold-ai
仓库: mindfold-ai/trellis
分类: 开发
安装次数: 110
GitHub Stars: 15,047

报告问题