Public Access
docs: create WIKI_STANDARDS
+222
@@ -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 |
|
||||
Reference in New Issue
Block a user