Software and hardware documentation sources for the Mo series. This repository maintains guides, specifications, media, design files, evidence and authoring metadata. The single Docusaurus website, standard components, search, previews and deployment are maintained in developer.
The unified website serves all documentation, including hardware pages and their downloads, under /docs/. The test platform is developer.inhand.online; the production target is developer.inhand.com, subject to infrastructure and release acceptance. The website is pre-release, so legacy /hardware-docs/ routes and old attachment paths are not kept; mo-docs releases contain content and do not deploy a website.
| Location | Maintained content |
|---|---|
docs/ |
Software guides, FAQ, board sections, shared Markdown/MDX and category metadata |
static/ |
Screenshots, licensed media, evidence and compatibility downloads |
hardware/products/, hardware/accessories/ |
Hardware specifications, interfaces, schematics, mechanical files and accessories |
hardware/training/ |
Maintenance training; excluded from product navigation |
content/hardware-map.json |
Hardware source-to-document route and public asset mapping |
validation/ |
Generated copy of a fixed developer content contract, with commit and hashes |
scripts/, tests/, .github/ |
Content and resource validation, repository governance and content releases |
Write normal Markdown. Use registered components for tabs, media, downloads and version tables; component implementation belongs in developer. Shared content and media imports are allowed. Hooks, network requests, arbitrary JavaScript, inline styles and imports from developer's internal src/ are rejected by the content contract. Teaching code inside fenced code blocks is unaffected. Excel remains a source document or attachment; new structured web data uses JSON.
Each file has one maintained source under hardware/; content/hardware-map.json places hardware pages and assets in the /docs/ navigation. Training and source/license evidence remain in the repository.
| Repository | Maintained source | Delivery responsibility |
|---|---|---|
| developer · GitLab | Website components, routes, search, integration and contracts | The complete website, release composition and deployment |
| mo-docs | Software/hardware tutorials, specifications, media, design files and training | Versioned content and reference assets |
| mo-tools | Toolchain/SDK selection, environment setup, reusable tools and Studio | Tool metadata and source packages |
| mo-models | Model catalog, compilation resources, compatibility and raw benchmarks | Model references, evidence and artifact status |
| mo-examples | Complete examples with related firmware, clients and configuration | Example sources and their requirements |
| Mo* · product repositories | Each product's BSP, drivers, root filesystem, image build and flashing | Product images and checksummed release metadata |
Mo* covers independently maintained product repositories such as Mo62A, Mo68A, Mo69A, Mo67A, Mo3588 and Mo3568. The framework does not fix their number. Hardware content and maintainer training are maintained in mo-docs.
Each source repository publishes ordinary versions. Developer alone has website RC/final channels. The target composition binds developer + mo-docs + mo-tools + mo-models + mo-examples + selected Mo* to exact commits and consumed-asset hashes. A new source release does not change an already frozen website combination. Tutorial applicability, PCB revisions, image versions and actual validation remain distinct.
| Operation | Write | Admin |
|---|---|---|
| Create, update or delete a topic branch | Allowed | Allowed |
Open a PR to master |
Allowed | Allowed |
Merge to master |
Not allowed | After required CI passes |
| Merge one's own PR | Not allowed | Same checks; no second approval required |
Direct push, force-push or delete master |
Not allowed | Blocked by the PR/check ruleset |
| Create remote Tags and start releases | Not allowed | Allowed; Tag CI validates after push |
GitHub uses two rulesets for master and two for all Tags. Permissions and merge checks are separate because bypass permissions apply to an entire ruleset.
| Ruleset | Scope | Rules / bypass |
|---|---|---|
admin-only-master-updates |
refs/heads/master |
Restricts creation/update/deletion/force-push; only Admin has bypass |
master-pr-and-required-checks |
refs/heads/master |
PR, up-to-date required checks, no deletion or force-push; no bypass; required approvals: 0 |
admin-only-tags |
All Tags | Restricts creation/update/deletion/force-push; only Admin has bypass |
tags-immutable |
All Tags | No updates, deletion or force-push; no bypass |
Required checks are commit-message and validate-content. Topic branches have no additional ruleset restriction. The repository automatically deletes eligible source branches after PR merge. Merge, squash and rebase remain available; when squashing, use the validated PR title and a conforming optional body, including room for GitHub's PR-number suffix.
Local hooks provide early feedback and can be bypassed locally; CI is the merge gate. Admins who can edit repository settings remain trusted operators. The separate immutable-Tag rule has no bypass: published Tags and Releases must not be rewritten or deleted in this workflow. Use a new ordinary version for corrections. No local or server-side Tag-creation hook is installed; an invalid Tag remains visible but fails CI before publication.
fix(download): keep the image and checksum on the same release
An English Conventional Commit title is sufficient. Add an English body when useful. Types are feat, fix, perf, docs, style, refactor, test, build, ci, chore, revert and sync; the lowercase scope is optional. Keep the title within 72 characters, start the subject with a lowercase letter and omit a final period. Separate a body with a blank line and wrap prose at 72 characters, except URLs and indented code. Do not add credentials, private infrastructure, Co-Authored-By or CI-skip markers.
npm ci installs this clone's commit-msg and pre-push hooks, so invalid messages fail at git commit, including git commit -m. CI checks the PR title and new non-merge commits again. Historical commits before the policy boundary are not rewritten. The policy is in repository-policy.json and policy.mjs.
Release notes use English entries in both editions. Only fixed headings and categories are translated, for example Features / 新功能, Fixes / 修复 and Documentation / 文档. Historical Message: en and Message.en: summaries remain readable; new commits do not need bilingual blocks. generate-changelog.mjs computes the range after the preceding ordinary release. Historical RCs remain traceable but are not a channel for new releases.
| Platform | Translation server | Status |
|---|---|---|
| GitLab | - | To be integrated |
| GitHub | - | To be integrated |
These are placeholders for future translation of change entries. The current generator runs without a translation API or credentials.
- Edit the owning source and open a PR. Content rules, downloadable-resource tests and commit policy must pass.
- An Admin merges after required CI. Use developer's integrated preview to check affected pages and links; mo-docs has no independent website build.
- Check remote Tag availability, then create an annotated
VX.Y.ZTag on an accepted master commit. New RC Tags are rejected; historical RCs remain unchanged. - CI validates and packages a content archive, file hashes, release metadata and bilingual-heading Changelogs, then publishes a complete ordinary GitHub Release through a draft.
- Developer selects that release in a subsequent website composition, builds and validates the complete site, then owns its release and deployment.
Assets are mo-docs-VERSION-content.tar.gz, content-manifest.json, release.json, CHANGELOG.en.md, CHANGELOG.zh-CN.md, release-notes.md and SHA256SUMS. They contain no site build or deploy credentials. Manual dispatch validates/packages without publication. Published Tags and assets are immutable; inspect failed draft publication before retrying and never overwrite a completed release.
nvm use
npm ci
npm test
# Install dependencies once in a sibling developer checkout, then:
npm run preview -- --port 8051Set DEVELOPER_DIR if the website checkout is elsewhere. Preview runs developer with this mo-docs directory as a local source override and refreshes edited content. Full website builds, browser checks and search indexing run in developer. npm run docs:diagrams regenerates the bilingual README diagrams.
See CONTRIBUTING.md, ARCHITECTURE.md and SECURITY.md. Content is CC BY-SA 4.0; third-party notices remain in static/ASSETS.md and beside their source files.
Website implementation lives in developer. Executable tutorial resources belong to mo-tools, mo-models and mo-examples; content/resource-map.json tells developer where to publish them under /docs/downloads/. This repository retains prose, images, design attachments and declarative firewall configuration. Developer release freezing and full-site rollout have separate acceptance.
Diagram source is maintained centrally in developer/scripts/render-architecture.mjs. Run npm run docs:diagrams, setting DEVELOPER_DIR if necessary, to regenerate this repository's six bilingual SVGs.
Maintain Mo62A specifications in specifications.json. Developer generates hardware documentation, product cards and specification tables from this file. OS and kernel versions come from pinned Mo62A release metadata. Integration expands the product-specifications marker; do not maintain a second specification table in prose.