Skip to content

contributing.mdx

Latest commit

 

History

History
231 lines (166 loc) · 6.27 KB

contributing.mdx

File metadata and controls

231 lines (166 loc) · 6.27 KB
title Contributing
description Share use cases with Hello ADP
enableComments true
author Steven Lynn
github_username stvlynn
x_username Stv_Lynn

Submit a Use Case

Follow these steps if you would like to add a new example to the project.

1. Fork the repository

} href="https://github.com/stvlynn/hello-adp/fork" title="Fork Repository" > Create your own copy of Hello ADP.

2. Clone your fork

After forking, copy the git URL for your repository—for example https://github.com/<your-username>/hello-adp.git.

image.png

Run the following command in the directory where you want to work:

git clone https://github.com/<your-username>/hello-adp.git

3. Edit the MDX content

We highly recommend an AI-assisted IDE such as Cursor, Windsurf, or Cline to speed up authoring.

Open the project in a new window and review the structure:

content/                   # Docs root
├── docs/                  # All documentation resources
│   ├── index.{lang}.mdx   # Landing page
│   ├── meta.{lang}.json   # Top-level navigation config
│   ├── contributing.{lang}.mdx # Contribution guide
│   ├── knowledge-base/    # Knowledge base docs
│   │   ├── meta.{lang}.json    # Navigation config
│   │   └── image-retrieval.{lang}.mdx # Knowledge base example
│   ├── plugin/            # Plugin docs
│   │   ├── meta.{lang}.json    # Plugin navigation
│   │   └── ... individual plugin docs
│   └── workflow/          # Workflow docs
│       ├── meta.{lang}.json    # Workflow navigation
│       ├── node/              # Node reference docs
│       │   └── ... node topics
│       ├── workflow-chatflow-difference.{lang}.mdx # Workflow vs. chatflow
│       └── twitter-mbti-receipt.{lang}.mdx # Twitter MBTI example

Each folder follows the same principles:

  1. meta.{lang}.json: controls ordering and structure in the navigation drawer. Example:

    {
    "title": "Section title",
    "icon": "remix-icon-name",
    "defaultOpen": true,
    "pages": [
        "doc-slug-1",
        "doc-slug-2",
        "sub-folder"
    ]
}

    We use the Remix Icon set throughout the project.

  2. *.mdx: the actual document. Always include a frontmatter block at the top:

    ---
title: Document title
description: Short description
enableComments: true
author: "Your name"
github_username: "your-github"
x_username: "your-x-account"
---

  3. Subfolders: further organize content. Each subfolder also needs its own meta.{lang}.json file.

Document filenames follow the document.{lang}.mdx convention.

  • Chinese: document.zh.mdx
  • English: document.mdx
  • Japanese: document.ja.mdx

Localization workflow (i18n)

Write one language first and let Cursor handle the rest.

The repo ships with an i18n rule at .cursor/rules/i18n.mdc.

Summon it with @i18n.mdc inside Cursor. A sample prompt:

Translate xxx.{lang}.mdx into xxx for the remaining locales.

image.png

The rule documents how to name files, update meta.{lang}.json, and keep variants in sync.

Images

Image hosting is limited through next.config.mjs. We currently allow sm.ms so assets stay centralized.

If you prefer a different CDN, update next.config.mjs accordingly while keeping assets well organized.

We strongly recommend capturing screenshots in English to make cross-language review easier.

4. Test locally

Run the project before opening a PR to make sure everything builds correctly.

Install dependencies

# npm
npm install

# or yarn
yarn

Start the dev server

# npm
npm run dev

# or yarn
yarn dev

Visit http://localhost:3000 and confirm your docs look good.

Verify i18n completeness

Important: every language variant must exist. Without an English (.mdx) file, other locales will fail to compile.

Make sure you have:

  1. English base file: document.mdx
  2. Chinese variant: document.zh.mdx
  3. Japanese variant: document.ja.mdx
  4. Navigation metadata for each locale: meta.json, meta.zh.json, meta.ja.json

Check with:

  • yarn build or npm run build
  • Watch for errors such as missing locale files, malformed frontmatter, mismatched entries in meta.json, or broken image URLs.

Inspect every locale in the browser:

  • English: http://localhost:3000/en/docs/...
  • Chinese: http://localhost:3000/zh/docs/...
  • Japanese: http://localhost:3000/ja/docs/...

All variants should render correctly and convey the same message.

5. Submit your changes

In your IDE, open the Git panel (), click , then choose Branches → Create branch.

2025-05-18 15.55.32.png

Pick a descriptive branch name such as docs/<slug> for documentation-only updates.

2025-05-18 15.56.41.png

Next, open a pull request with your branch:

} href="https://github.com/stvlynn/hello-adp/compare" title="Pull Request" > Create a PR for review.

Submit a use case or feedback

If you have an idea but would like us to draft the final copy, open an Issue in this repository.

} href="https://github.com/stvlynn/hello-adp/issues/new" title="GitHub Issue" > Share a use case or request support.

Use the following template:

## Title
[Provide a short title for the use case]

## Description
[Describe what the workflow or demo accomplishes]

## Project links
[List any relevant repos, workflow DSL files, or demos]

## Source material
[Attach references such as READMEs or articles]

## Additional notes
[Any other context reviewers should know]

We will review the Issue, follow up with any questions, and publish the documentation after acceptance.