| name | bagisto-documentation |
| description | Use when writing or updating any Bagisto documentation site — the developer documentation, the merchant user guide, or any other Bagisto docs repository — covering page content, code samples, screenshots, the sidebar, image naming, and moving or deleting pages. Trigger phrases include "docs", "documentation", "user guide", "developer documentation", "dev docs", "merchant documentation", "marketplace docs", "document this", "update the docs", "add a doc page", "screenshot", "ImagePopup", "redirect a doc page". |
| requires | bagisto-coding-standards |
| license | MIT |
Bagisto Documentation
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.
Step 1: decide who the reader is
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.
Step 2: find the repository, do not guess it
Each site is a separate repository, not a folder inside the Bagisto app, so
locate it before editing anything:
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.
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.
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 |
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
npm run docs:dev
npm run docs:build
Learn the site rather than assuming it. The sites differ in ways that matter
and that change over time, so check rather than recall:
grep -n "app.component(" .vitepress/theme/index.ts
grep -ohE "'/[0-9][^/]*" .vitepress/_redirects.ts | tr -d "'" | sort -u
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.
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.
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.
