contribute

Trellis への貢献

貢献の対象は、次の 2 つのリポジトリに分かれています。

内容	リポジトリ	目的
ドキュメントページ	mindfold-ai/docs	Mintlify ドキュメントサイト
スキルと仕様テンプレート	mindfold-ai/Trellis	marketplace/ ディレクトリ

docs リポジトリの構成

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 にすると、グループはデフォルトで折りたたまれます

仕様テンプレートへの貢献

仕様テンプレートは、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. ドキュメントページを作成する（docs リポジトリに両言語で作成）

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

次のフロントマターを使用してください。

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

スキルへの貢献

スキルは、Trellis のメインリポジトリの marketplace/skills/ にあります。

1. スキルディレクトリを作成する

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

SKILL.md の形式については、Codex Skills のドキュメントを参照してください。

2. index.json に登録する

Trellis リポジトリの marketplace/index.json にスキルを追加します。

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

3. ドキュメントページを作成する（docs リポジトリに作成）

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

4. docs.json のナビゲーションを更新する

Skills のネストしたグループを見つけ、両言語にページを追加します。

5. 概要ページを更新する

次のファイルにある表へスキルを追加します。

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

インストール

ユーザーは次の方法でスキルをインストールします。

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

ショーケースプロジェクトへの貢献

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 コンポーネントを追加します。

英語（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>

ドキュメントへの貢献

新しいガイドを追加する

1. guides/your-guide.mdx にページを作成します
2. zh/guides/your-guide.mdx に中国語版を作成します
3. docs.json を更新し、両言語の Guides グループに追加します

ブログ記事を追加する

1. blog/your-post.mdx にページを作成します
2. zh/blog/your-post.mdx に中国語版を作成します
3. docs.json を更新し、両言語の Tech Blog グループに追加します

既存のページを更新する

1. 該当するディレクトリでファイルを見つけます
2. 変更を加えます
3. 両言語版の内容が一致していることを確認します

バイリンガル要件

ユーザー向けコンテンツはすべて、英語版と中国語版の両方を用意してください。

コンテンツの種類	英語版のパス	中国語版のパス
ホームページ	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 リポジトリ）：

1. フォークします：https://github.com/mindfold-ai/docs
2. クローンします：git clone https://github.com/YOUR_USERNAME/docs.git
3. インストールします：pnpm install
4. ブランチを作成します：git checkout -b feat/your-contribution
5. このガイドに沿って変更を加えます
6. テストします：pnpm dev
7. 規約に沿ったメッセージでコミットします（例：docs: add xxx template）
8. プッシュして PR を作成します

スキル／仕様テンプレートの場合（Trellis リポジトリ）：

1. フォークします：https://github.com/mindfold-ai/Trellis
2. クローンします：git clone https://github.com/YOUR_USERNAME/Trellis.git
3. スキル／テンプレートを marketplace/ に追加します
4. marketplace/index.json を更新します
5. プッシュして PR を作成します

PR 提出前のチェックリスト

• 英語版と中国語版の両方を作成した（ドキュメントページの場合）
• 両言語の docs.json を更新した（ドキュメントページの場合）
• marketplace/index.json を更新した（スキル／テンプレートの場合）
• 概要／インデックスページに新しい項目を追加した
• ローカルプレビューをテストした（pnpm dev）
• リンク切れがない
• コードブロックに正しい言語タグを設定した
• frontmatter にタイトルと説明を含めた
• 画像を images/ ディレクトリに配置した（画像がある場合）