bagisto-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bagisto Documentation

Bagisto 文档指南

Bagisto's documentation lives in separate repositories from the codebase, one per audience. They are all VitePress sites built the same way, so the mechanics in this skill apply to every one of them — the developer documentation, the merchant user guide, and any guide added later.

Bagisto的文档存储在与代码库分离的独立仓库中，每种受众对应一个仓库。这些文档站点均基于VitePress构建，因此本技能中的操作规则适用于所有文档——包括开发者文档、商家用户指南以及后续新增的任何指南。

Step 1: decide who the reader is

步骤1：确定目标读者

Everything else follows from this, so settle it before writing a line. Judge by audience, not by which repository you happen to have open — a repository can hold a page aimed at either reader, and getting this wrong produces a page that is technically accurate and useless to whoever arrives.

Ask	If yes	Load
Will the reader write code against Bagisto — a package, a theme, an integration, an API client?	Developer documentation	developer-docs.md
Will the reader operate a store from the admin panel, without touching code?	User guide	user-guide.md

If a page seems to need both, it is two pages. A merchant reading about a class name skips it; a developer reading a click path stops trusting the page. Split by audience and link across.

When a new documentation repository appears — a marketplace guide, a self-hosting guide — it is one of these two readers under a new name. Run the same test and use the same reference.

所有后续操作都以此为基础，因此在开始撰写前需先明确这一点。根据受众判断，而非当前打开的仓库——一个仓库中可能包含面向不同读者的页面，若判断错误，页面即使技术准确，对目标读者而言也毫无用处。

问题	如果是	参考文档
读者是否会针对Bagisto编写代码——如开发包、主题、集成或API客户端？	开发者文档	developer-docs.md
读者是否会通过管理后台运营店铺，无需接触代码？	用户指南	user-guide.md

若某页面似乎需要同时面向两类读者，应拆分为两个页面。商家看到类名称会直接跳过；开发者看到点击操作步骤会不再信任该页面。按受众拆分并添加跨页面链接。

当出现新的文档仓库——如市场指南、自托管指南——本质上仍是上述两类读者的延伸，需执行相同的判断并使用对应的参考文档。

Step 2: find the repository, do not guess it

步骤2：找到对应仓库，切勿猜测

Each site is a separate repository, not a folder inside the Bagisto app, so locate it before editing anything:

bash

find . ~ -maxdepth 6 -type d -path '*/src' -path '*doc*' 2>/dev/null | head

If it is not cloned, ask the user for the path or to clone it. Never invent a location and never write a page into the Bagisto app by mistake — the app has no

src/

docs tree, so a page created there is silently lost.

每个文档站点都是独立仓库，而非Bagisto应用内的文件夹，因此在编辑前需先定位到正确的仓库：

bash

find . ~ -maxdepth 6 -type d -path '*/src' -path '*doc*' 2>/dev/null | head

若尚未克隆该仓库，请向用户询问路径或请求克隆。切勿自行编造位置，也不要错误地将页面写入Bagisto应用——应用内没有

src/

文档目录，在此创建的页面会被无声丢弃。

Read the neighbours before writing

撰写前参考同类页面

Open two or three existing pages in the section you are adding to and match their depth, heading rhythm and tone. A page that reads differently from its neighbours is a defect even when every fact in it is right.

Check for duplication at the same time: if the topic is already half-covered somewhere, extend that page or cross-link to it rather than forking a second source of truth. Two pages that partly answer the same question age into two pages that contradict each other.

打开你要新增页面所在板块的2-3个现有页面，匹配它们的内容深度、标题节奏和语气。即使页面内容全部正确，若与同类页面风格差异过大，也属于缺陷。

同时检查是否存在内容重复：若主题已在其他地方部分覆盖，应扩展该页面或添加跨链接，而非创建第二个信息源。两个部分回答同一问题的页面最终会演变为相互矛盾的内容。

Reference files

参考文件

File	Load when
developer-docs.md	Writing for a reader who writes code — voice, structure, code samples
user-guide.md	Writing for a reader who runs a store — voice, page shape, steps
screenshots.md	A page needs an image — capture, clean setup, naming
publishing.md	Adding, moving or deleting a page — sidebar, redirects, verification

文件	使用场景
developer-docs.md	面向编写代码的读者——语气、结构、代码示例
user-guide.md	面向运营店铺的读者——语气、页面结构、操作步骤
screenshots.md	页面需要添加图片时——截图、环境配置、命名规则
publishing.md	添加、移动或删除页面时——侧边栏配置、重定向、验证

What every site has in common

所有文档站点的共性结构

<docs-repo>/
├── src/                       # srcDir — every page
│   ├── <section>/*.md          # one folder per sidebar group
│   ├── index.md
│   └── public/
│       ├── images/<section>/   # per-section image folders
│       ├── llms.txt            # hand-maintained
│       └── llms-full.txt       # hand-maintained
└── .vitepress/
    ├── config.mts              # sidebar, nav, build hooks
    ├── _redirects.ts           # legacy URL map
    └── theme/                  # site-specific Vue components

bash

npm run docs:dev      # local preview
npm run docs:build    # the gate — always run before calling a change done

Learn the site rather than assuming it. The sites differ in ways that matter and that change over time, so check rather than recall:

bash

grep -n "app.component(" .vitepress/theme/index.ts        # custom components, e.g. an image viewer
grep -ohE "'/[0-9][^/]*" .vitepress/_redirects.ts | tr -d "'" | sort -u   # legacy version prefixes

The second one matters most: a page that moves needs its redirect repointed under every prefix that site carries, and the count is not the same between repositories.

<docs-repo>/
├── src/                       # 源目录——所有页面存放位置
│   ├── <section>/*.md          # 每个侧边栏分组对应一个文件夹
│   ├── index.md
│   └── public/
│       ├── images/<section>/   # 按板块划分的图片文件夹
│       ├── llms.txt            # 手动维护
│       └── llms-full.txt       # 手动维护
└── .vitepress/
    ├── config.mts              # 侧边栏、导航栏、构建钩子配置
    ├── _redirects.ts           # 旧版URL映射
    └── theme/                  # 站点专属Vue组件

bash

npm run docs:dev      # 本地预览
npm run docs:build    # 验证环节——完成修改前必须执行

了解站点实际情况，不要想当然。 各站点存在重要差异且会随时间变化，因此应主动检查而非凭记忆判断：

bash

grep -n "app.component(" .vitepress/theme/index.ts        # 自定义组件，如图片查看器
grep -ohE "'/[0-9][^/]*" .vitepress/_redirects.ts | tr -d "'" | sort -u   # 旧版版本前缀

第二条命令尤为重要：页面移动时，需为该站点包含的所有前缀重新配置重定向，且不同仓库的前缀数量可能不同。

Non-negotiables

不可违反的规则

Write for one reader. The audience decided in step 1 governs vocabulary, what you explain and what you assume. This is the rule that makes a docs page good or useless.
A published URL never breaks. Every way a page's URL can change — renaming the file, moving it to another section, changing its slug, splitting it in two, deleting it — needs an entry in
```
.vitepress/_redirects.ts
```
pointing the old URL at the content's new home, and every existing redirect that aimed at the old URL repointed. Nobody updates their links for you. See publishing.md.
Never delete a page that is holding a URL open unless a redirect covers that URL first. Some pages exist only to keep a legacy path resolving; they look like clutter and are load-bearing.
The sidebar is the only navigation. A page absent from the
```
sidebar
```
array in
```
.vitepress/config.mts
```
is reachable only by typing its URL. Add the entry in the same change as the page.
Every filename is kebab-case. Lowercase, hyphen-separated, no spaces, no camelCase, no underscores — for pages and images alike. Older files predate the rule; match the rule, not the neighbours, and do not rename unrelated files while you are there.
Verify claims against the codebase, not memory. A confidently wrong sentence is worse than no page, because it is believed. Open the file, run the command, check the string.
llms.txt
and
llms-full.txt
are written by hand. Nothing generates them. Adding, moving or deleting a page means editing them too.
The build is the gate.
```
npm run docs:build
```
reports each redirect it writes. A change that has not been built has not been checked.

面向单一读者撰写。 步骤1确定的受众决定了词汇选择、需要解释的内容以及可以默认读者已知的信息。这是决定文档页面优劣的核心规则。
已发布的URL绝不允许失效。 页面URL的任何变化——重命名文件、移动到其他板块、修改slug、拆分或删除页面——都需要在
```
.vitepress/_redirects.ts
```
中添加条目，将旧URL指向内容的新位置，同时需更新所有指向旧URL的现有重定向。不会有人主动为你更新外部链接。详情见publishing.md。
除非已配置重定向，否则绝不删除占用URL的页面。 有些页面仅用于保留旧路径；它们看似多余，实则至关重要。
侧边栏是唯一的导航方式。 未添加到
```
.vitepress/config.mts
```
中
```
sidebar
```
数组的页面只能通过直接输入URL访问。添加页面时需同步添加侧边栏条目。
所有文件名均使用kebab-case格式。 小写、连字符分隔，无空格、无驼峰式命名、无下划线——页面和图片文件名均需遵守此规则。旧文件可能未遵循该规则，但新文件需严格遵守，且不要在修改时重命名无关文件。
依据代码库验证内容，而非凭记忆。 自信的错误表述比没有页面更糟糕，因为读者会相信它。打开文件、执行命令、检查字符串。
llms.txt
和
llms-full.txt
为手动维护文件。无自动生成机制。添加、移动或删除页面时需同步编辑这两个文件。
构建是验证的关键环节。
```
npm run docs:build
```
会报告所有已写入的重定向。未执行构建的修改视为未完成检查。

Common mistakes

常见错误

Mixing the two audiences on one page — the failure this skill exists to prevent. Click paths in developer docs, class names in the user guide.
Documenting the intended design instead of the shipped behaviour. When a page and the code disagree, the code is right.
A stub page left behind after a move. A page whose whole body is "this moved" stays in the sidebar and ranks in search. Redirect it, then delete it.
A rename shipped without a redirect. Fixing a typo in a filename feels like tidying rather than a URL change, which is why it is the one that gets missed.

REQUIRED SUB-SKILL: Use bagisto-change-verification before calling any change done.

在同一页面混合两类受众内容——这正是本技能要避免的核心问题。比如在开发者文档中加入点击操作步骤，或在用户指南中提及类名称。
记录设计意图而非实际已发布的功能。 当文档与代码不一致时，以代码为准。
页面移动后遗留占位页面。 仅包含“此页面已迁移”内容的页面仍会出现在侧边栏并被搜索引擎收录。应先配置重定向，再删除该页面。
重命名文件但未配置重定向。 修改文件名中的拼写错误看似只是整理，但这属于URL变更，也是最容易被遗漏的操作。