adding-projects.md

Adding Documentation Sources

1MB-Plugins-Docs assembles several independently maintained documentation sources into one site. It is the sole Starlight builder and GitHub Pages publisher.

Ownership Model

Each source project owns exactly one ID and one imported directory:

project-docs/<project-id>/

Generated player pages use the matching ID:

src/content/docs/player-guides/custom-server-plugins/<project-id>/

No project may write to the complete project-docs/ or src/content/docs/ trees. Pull the latest public main before importing and review the resulting namespace-scoped diff before committing.

Standalone Custom Projects

A source project must contain:

README.md
docs/
  plugin-docs.yml
  player-guide.md

It may also provide commands, permissions, placeholders, configuration, installation, integrations, and troubleshooting pages.

An imported project may opt into three public-safe extensions without changing any existing source:

• public_readme selects a reviewed file under docs/ to mirror as the namespace README.md instead of exposing the source repository's root README.
• staff_guide renders a first-class page under /staff-reference/custom-server-plugins/<id>/.
• staff_documents is an optional slug-to-file map that renders public-safe child pages below that staff route. Slugs and files stay inside the project's imported namespace.
• catalogue_json and catalogue_csv publish an isolated searchable price-catalogue page plus namespaced static assets. Both catalogue paths are required together and must stay under docs/.

Minimum manifest:

id: lootbox
name: Lootboxes
category: custom-server-plugin
summary: Collect and open server lootboxes containing configured rewards.
main_command: /lootbox
docs_url: https://docs.1moreblock.com/custom-server-plugins/lootbox/
player_guide: player-guide.md
technical_readme: ../README.md
java_target: "25"
paper_target: "26.2"
official_project: true
repository: mrfdev/1MB-Lootbox

Example public-safe staff/catalogue additions:

staff_guide: staff-guide.md
staff_documents:
  commands: commands.md
  permissions: permissions.md
public_readme: technical-overview.md
technical_readme: technical-overview.md
catalogue_json: catalogue/price-catalogue.json
catalogue_csv: catalogue/price-catalogue.csv

The catalogue UI inserts imported strings with DOM textContent, never as HTML. Source projects remain responsible for publishing only sanitized catalogue fields; the site validator verifies paths and generated ownership, not whether private source data was safe to export.

IDs use lowercase letters, numbers, and single hyphens. The canonical URL must exactly match the category and ID. Build numbers never belong in documentation URLs.

Import or refresh the source:

npm run docs:import -- --source ../1MB-Lootbox
npm run docs:generate
npm run docs:validate
npm run build

After the first import, docs-sources.json records the project. Refresh it with:

node scripts/sync-docs.mjs --project lootbox
npm run docs:generate

Other Server Features

Third-party features are curated directly in this repository rather than copied from vendor wikis:

catalog/other-server-features/<feature-id>/
  plugin-docs.yml
  player-guide.md
  staff-guide.md

Use category: other-server-feature, the canonical /other-server-features/<id>/ URL, and an official_wiki link. Explain the feature as configured on 1MoreBlock, including enabled commands, restrictions, ranks, worlds, and server-specific differences. Set staff_guide: staff-guide.md when a rendered public-safe technical reference is available. Do not reproduce copyrighted wiki pages.

BentoBox Command Conventions

1MoreBlock runs several BentoBox game modes together, so player documentation must use the configured full root for the relevant mode:

Game mode	Player root	Staff administration root
OneBlock	/oneblock	/adminoneblock
ChunkBlock	/chunkblock	/adminchunkblock
SkyBlock	/skyblock	/adminskyblock
AcidIsland	/acid	/adminacid
CaveBlock	/cave	/admincave
SkyGrid	/skygrid	/adminskygrid

Do not publish the upstream generic island or shortened OneBlock aliases as 1MoreBlock commands. For add-ons, prefix the subcommand with every enabled mode's full root, such as /skyblock greenhouse or /oneblock greenhouse. Staff game-mode administration puts admin before the mode name; it is not appended to the player command. BentoBox platform commands such as /bentobox version remain unchanged.

npm run docs:validate checks curated BentoBox manifests and guides for deprecated player roots and postfix admin forms.

Public-Safety Rules

• Verify commands, permissions, placeholders, versions, and behavior from the source project.
• Publish player guidance and public-safe staff administration details only.
• Never publish credentials, private endpoints, paid files, databases, exploit-sensitive values, source code, or internal incident procedures.
• Use portable placeholders or repository-relative paths in public examples. Validation rejects macOS, Linux, and Windows user-profile paths from every registered project namespace.
• Keep internal plans, ADRs, agent instructions, task/review records, live operational baselines, and similar engineering material in the private source. Declare every private path in the source repository's .public-docs-excludes, relative to docs/.
• For high-risk sources, mirror the mandatory exclusions in docs-sources.json as requiredPrivateDocs. Synchronization must fail if the source removes or narrows a required exclusion, and validation must fail if a guarded path appears in project-docs/.
• Treat .gitignore as defense in depth only. It cannot prevent a sync script or site generator from reading a file that exists in the working tree.
• Keep source documentation in its source project; do not hand-edit its mirrored copy.
• Prefer public_readme when a source root README contains private development, release, or operational evidence.
• Do not hand-edit generated Starlight pages. Change the source guide and regenerate.
• Never force-push the public documentation repository as part of an individual project sync.

Publishing Checklist

1. Classify every new or changed source document as public-safe or private before synchronization.
2. Update .public-docs-excludes and any matching requiredPrivateDocs policy before syncing.
3. Commit and push the source project's code and documentation.
4. Pull the latest 1MB-Plugins-Docs/main.
5. Import only the changed project namespace.
6. Confirm SYNCED_FROM.md lists the expected source and required exclusions.
7. Run npm test.
8. Run npm run docs:generate, npm run docs:check, and npm run docs:validate.
9. Run npm run build and review the complete diff, including removed and newly added files.
10. Confirm no guarded internal path exists under project-docs/ or generated site output.
11. Commit and push the public repository separately.
12. Confirm the GitHub Pages workflow and live canonical page.