📝 Contributing to the Wiki

The wiki is a Docusaurus 3 site. All source files are in the z-shell/wiki repository. English is the source language; translations are managed via Crowdin.

Prerequisites

• Node.js ≥ 20
• pnpm ≥ 10

Local Development

git clone https://github.com/<your-username>/wiki.git
cd wiki
pnpm install          # install dependencies
pnpm start            # dev server at http://localhost:3000

Other useful commands:

Command	Purpose
pnpm build	Full production build
pnpm build:en	English-only build (faster for docs-only checks)
pnpm serve	Serve the production build locally
pnpm clear	Clear Docusaurus cache (use when the site behaves oddly)
pnpm lint	Run all linters (ESLint + Stylelint via Trunk)
pnpm lint:fix	Auto-fix linting issues
pnpm write-heading-ids	Regenerate heading IDs across all docs

Content Roots

The wiki has three independent docs roots:

Directory	URL Prefix	Purpose
docs/	/docs	Core documentation, getting started, guides
community/	/community	Community guides, Zsh plugin standard
ecosystem/	/ecosystem	Annexes, packages, plugins

File Naming Conventions

• Numeric prefixes control sidebar order: 01_first.mdx, 02_second.mdx
• Directories need a _category_.json file (see below)
• All English source files only — never edit files under i18n/

Frontmatter

Every .mdx file requires these fields:

---
id: unique_page_id
title: "Page Title"
sidebar_position: 1
image: /img/png/theme/z/320x320.png
description: One-sentence description for SEO.
keywords:
  - relevant
  - keywords
---

_category_.json

Required for every new directory:

{
  "label": "📁 Section Name",
  "position": 1,
  "link": {
    "type": "generated-index"
  }
}

MDX Authoring Patterns

Admonitions

Use Docusaurus admonitions for callouts instead of blockquotes:

:::tip
Helpful hint.
:::

:::info
Neutral information.
:::

:::warning
Something to be cautious about.
:::

:::danger
Critical warning.
:::

Global MDX Components

These components are available in every .mdx file without importing:

Component	Usage
<Highlight color="...">text</Highlight>	Colored text spans
<Emoji symbol="🎉" label="party"/>	Accessible emoji
<GhRepoBadge repo="z-shell/zi"/>	GitHub repo badge
<ShellCodeCopy>command</ShellCodeCopy>	Copyable shell command

Code Blocks

Use language identifiers and showLineNumbers when helpful:

```zsh showLineNumbers
zi light z-shell/F-Sy-H
```

Links

Prefer relative links between pages:

See [Getting Started](../getting_started) for more details.

Use absolute URLs only for external resources.

Branch and PR Workflow

1. Branch from next: git checkout -b docs/my-page next
2. Make changes to English source files only
3. Run pnpm build:en to catch broken links and MDX errors
4. Open a PR targeting next

Never edit i18n/ files directly

Translation files under i18n/ are managed exclusively through Crowdin. Manual edits will be overwritten on the next sync.

Localization

The wiki supports multiple languages via Crowdin. To contribute a translation:

1. Join the project at translate.zshell.dev
2. Translate strings in the Crowdin editor
3. Approved translations are synced back to the repo automatically

Do not fork the repo and edit i18n/ files manually.

Style Guidelines

• Use sentence case for headings (e.g., ## Code of conduct, not ## Code Of Conduct)
• Keep paragraphs short — aim for ≤ 5 sentences per paragraph
• Prefer tables for structured comparisons
• Use admonitions sparingly — only when the callout level genuinely matches the content
• Formatting is enforced by Prettier (120-char print width, double quotes, 2-space indent)

See Also

• Getting Started — org-wide branch and commit conventions
• Project Management — how work is tracked