Skip to content

docs: complete WebShopX documentation restructure - #2

Merged
Cc-Cece merged 54 commits into
mainfrom
agent/webshopx-docs-restructure
Jul 26, 2026
Merged

Cc-Cece merged 54 commits into
mainfrom
agent/webshopx-docs-restructure

Conversation

@Cc-Cece

@Cc-Cece Cc-Cece commented Jul 26, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

This PR completes the WebShopX documentation restructuring pass and turns the docs into a role-based, task-oriented structure with explicit reference/source-of-truth boundaries.

Information architecture

  • Added a dedicated WebShopX Getting Started page.
  • Reworked the WebShopX sidebar into:
    • Player Guide
    • Server Administrator
    • Developer
    • Reference
  • Kept WebShopX-Payments as a separate product section while documenting its relationship to WebShopX core.
  • Added a Reference index that points to the authoritative config, command, API, error, glossary, and migration pages instead of duplicating parameters.

Player documentation

  • Rewrote Quick Start around the current v3 flow: /ws password -> /ws home -> web login.
  • Removed stale registration-oriented guidance from the normal player path.
  • Updated mailbox usage to /ws mailbox collect.
  • Simplified the web-inventory page so players see online/read-only/experimental behavior without low-level playerdata implementation details.
  • Added explicit Stable / Beta / Experimental semantics to the player guide.

Server administrator documentation

  • Rebuilt configuration.md from the current WebShopX config.yml baseline.
  • Removed draft-only/non-shipped config keys from the primary configuration example.
  • Reworked installation/deployment around SQLite, MySQL/MariaDB, internal, external, and relay modes.
  • Clarified the v3 admin entry behavior and bootstrap-account security requirements.
  • Updated current commands and permissions and removed old v2 command guidance from the primary workflow.
  • Fixed broken links in the administrator overview and aligned it with the actual page filenames.
  • Normalized filenames to install-deploy.md and commands-permissions.md while preserving document IDs/routes.

Developer documentation

Promoted the former hidden .dev/dev/* material into public docs/webshopx/developer/* documentation:

  • developer overview
  • HTTP API basics
  • authentication and sessions
  • player API
  • market API
  • admin API
  • errors and idempotency
  • uploads and static assets
  • integration playbook

The superseded hidden .dev/dev/* copies were removed so the public developer docs are now the maintenance source.

The existing WebShopXPaymentApi guide remains the Java/plugin-side Payment Provider integration entry.

English i18n

  • Updated the English site landing page, player overview/quick start, administrator overview/configuration, install/deploy, and commands/permissions.
  • Added English Getting Started, Developer Overview, Reference, core HTTP API pages, and web-inventory guidance.
  • Migrated the English admin translation paths to match the normalized source paths and removed the old orphaned paths.

Source-of-truth policy introduced by this restructure

  1. The WebShopX version's code / shipped configuration is authoritative.
  2. Reference documentation summarizes that implementation.
  3. Player/admin guides explain task flows without duplicating whole parameter sets.
  4. README files, old screenshots, and third-party guides are secondary references.

Validation performed

  • Compared the full branch against main; the branch is based directly on current main and is not behind it.
  • Reviewed sidebar document IDs and normalized source/i18n paths.
  • Checked the repository's frontmatter validation requirements; all newly added docs/webshopx/* pages include kebab-case IDs, titles, and sidebar positions.
  • Cross-checked high-impact WebShopX facts against the connected Cc-Cece/WebShopX repository, including current config.yml, plugin.yml, deployment modes, and API implementation locations.
  • Attempted to run the repository validation/build locally, but this execution environment cannot resolve github.com, so a fresh checkout/dependency install cannot be completed here.
  • The current PR head has no reported GitHub commit-status checks, so final Docusaurus rendering/build validation still needs repository CI or a local preview.

Manual review requested

Please focus manual preview on:

  1. WebShopX sidebar/category navigation (ZH and EN)
  2. relative links from Getting Started / Developer / Reference pages
  3. administrator install/config pages
  4. player Quick Start and web-inventory pages
  5. English route/path migration

The PR intentionally remains Draft until that visual/build review is completed.

Cc-Cece added 30 commits July 26, 2026 14:08
@Cc-Cece Cc-Cece changed the title docs: restructure WebShopX documentation docs: complete WebShopX documentation restructure Jul 26, 2026
@Cc-Cece
Cc-Cece merged commit 25eb268 into main Jul 26, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant