diff --git a/WIKI_STANDARDS.md b/WIKI_STANDARDS.md new file mode 100644 index 0000000..081a7a0 --- /dev/null +++ b/WIKI_STANDARDS.md @@ -0,0 +1,222 @@ +[← Back to Home](Home) + +# Wiki Standards + +Standards and conventions for all wiki documentation across the Moko Consulting ecosystem. + +--- + +## Page Structure + +Every wiki page must follow this structure: + +```markdown +[← Back to Home](Home) + +# Page Title + +Brief description of what this page covers. + +--- + +## Section 1 +Content... + +## Section 2 +Content... + +--- + +## Related + +- [Other Page](Other-Page) -- description +- [External Link](https://...) -- description + +--- + +*Repo: [RepoName](repo-url) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | YYYY-MM-DD | Author | Initial version | +``` + +### Required elements + +| Element | Location | Purpose | +|---|---|---| +| Navigation link | First line | `[← Back to Home](Home)` | +| H1 title | After nav | Page title matching the wiki page name | +| Description | After title | 1-2 sentence summary | +| Horizontal rules | Between major sections | `---` separators for visual clarity | +| Related section | Before footer | Links to related pages and external resources | +| Metadata footer | Last lines | Repo link, MokoStandards link, revision table | + +--- + +## Home Page Standard + +Every repo wiki must have a Home page with: + +| Section | Required | Description | +|---|---|---| +| H1 project name | Yes | Project name as heading | +| Tagline | Yes | One-sentence description | +| Info table | Yes | Type, language, license, platform | +| Overview | Yes | Key context about the project | +| Wiki pages index | Yes | Organized links to all wiki pages, grouped by category | +| Related wikis | Recommended | Links to related project wikis | +| MokoStandards backlink | Yes | Link to moko-platform wiki Home | + +### Info table format + +```markdown +| Field | Value | +|---|---| +| **Type** | MCP Server / Joomla Template / Joomla Plugin / etc. | +| **Language** | PHP / TypeScript / Bash | +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](repo-url) · [GitHub](mirror-url) | +``` + +--- + +## Content Guidelines + +### Formatting + +| Rule | Example | +|---|---| +| Use tables for structured data | Not bullet lists for key-value pairs | +| Use code blocks for commands | `` `make build` `` or fenced blocks | +| Use headers for sections | H2 for major sections, H3 for subsections | +| Use horizontal rules between sections | `---` | +| No emojis in headers | Use plain text | +| Em dashes | Use `--` not unicode `—` | + +### Writing style + +- **Concise** -- lead with the answer, not the explanation +- **Scannable** -- headers, tables, and short paragraphs +- **Accurate** -- built from actual source code, not assumptions +- **Actionable** -- include commands, file paths, and examples +- **Current** -- update when code changes + +### Code blocks + +Always specify the language: + +````markdown +```bash +make build +``` + +```json +{"key": "value"} +``` + +```php +$app = Factory::getApplication('site'); +``` +```` + +--- + +## Page Categories + +Organize wiki pages into these standard categories on the Home page: + +| Category | Content | +|---|---| +| **Guides** | Step-by-step tutorials (Installation, Configuration, Getting Started) | +| **Reference** | Technical reference (API, Tools, CSS Variables, Endpoints) | +| **Operations** | Operational procedures (Backup, Restore, Monitoring, Troubleshooting) | +| **Architecture** | System design (Architecture, How It Works, Data Flow) | +| **Development** | Contributing (Development, Release Process, Testing) | + +--- + +## Naming Conventions + +| Type | Format | Example | +|---|---|---| +| Guide pages | Title case, hyphenated | `Installation`, `Getting-Started` | +| Reference pages | UPPER_CASE for standards | `WIKI_STANDARDS`, `MINIFICATION` | +| Technical pages | Title case | `Architecture`, `Configuration` | +| Compound names | Hyphenated | `Custom-Themes`, `Backup-Recovery` | + +--- + +## Metadata Footer + +Every page ends with a metadata footer containing: + +1. **Repo link** -- link to the source repository +2. **MokoStandards link** -- link to the central standards wiki +3. **Revision history table** -- tracks changes to the page + +### Format + +```markdown +--- + +*Repo: [RepoName](https://git.mokoconsulting.tech/Owner/Repo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | +| 1.1 | 2026-05-10 | Moko Consulting | Added troubleshooting section | +``` + +### Rules + +- Increment minor version for content updates (1.0 → 1.1) +- Increment major version for restructuring (1.x → 2.0) +- Author is always "Moko Consulting" for org work +- Date is ISO format (YYYY-MM-DD) + +--- + +## Wiki Health Requirements + +The `check_wiki_health.php` validation checks: + +| Check | Requirement | +|---|---| +| Home page exists | Required | +| MokoStandards backlink | Required on Home page | +| Page count | At least 1 (Home) | +| Navigation links | `[← Back to Home](Home)` on all non-Home pages | +| Metadata footer | Repo link + revision table on all pages | + +--- + +## GitHub Mirror + +All wikis are backed up daily to [mokoconsulting-tech/wiki](https://github.com/mokoconsulting-tech/wiki) on GitHub via `sync-wikis-to-github.sh` (runs daily at 5am UTC). + +Structure: +``` +wiki/ + README.md (auto-generated index) + moko-platform/ (30+ pages) + MokoOnyx/ (9 pages) + monitor-mcp/ (6 pages) + ... +``` + +--- + +## Related + +- [MINIFICATION](MINIFICATION) -- asset build standards +- [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD conventions +- [Documentation-Standards](Documentation-Standards) -- code documentation standards + +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial wiki standards document |