OpenShellOrg documentation hub. Antora site aggregating openshellorg projects (SOS + companion tooling docs).
Explore the docs
Report Bug
·
Request Feature
Table of Contents
Documentation hub for OpenShellOrg — Antora site aggregating org projects, plus SOS certification packages in this monorepo. The published site follows the facto-stack Antora compose pack (Valentus + Lunr + page-context + site-nav-tree + maint extensions), aligned with DevCentr docs.
Two complementary tracks:
- Standardized Operations Syntax (SOS) — unify human-friendly CLI flag syntax and certify compliant tools ("Save Our Syntax").
- Structured shell architecture — advocate typed data pipelines (endorse Nushell) so stdout is not forced to be both a pipe and a display canvas. Do not reinvent Nushell; document the model and ship helpers.
SOS remains the certification/flag work in this monorepo. Structured-shell direction lives in sibling repos (below).
| Repo | Role |
|---|---|
| shell-architecture | Thesis and layers: structured I/O, SOS, terminals, Dev-Centr relationship |
| nu-require | validate() — require / relaunch under Nushell; optional install offer |
| nu-emit | C-first API to emit structured rows (JSONL) without hand-rolling JSON |
Name collision: We are not NVIDIA OpenShell (agent sandbox runtime). Different problem, similar words.
Dev-Centr recommends/configures Nushell for developers; OpenShellOrg standardizes and tools. Keep the orgs aligned, not merged.
docs/ # this repo (openshellorg/docs)
├── apps/
│ └── main/ # Main website (SolidStart)
├── docs/ # Antora hub component (SOS, philosophy, ecosystem)
├── docs-tools/ # Antora `tools` component ROOT (member modules in sibling repos)
├── packages/
│ ├── sos-grammar/ # @sos/grammar
│ └── sos-validator-core/
├── assets/brand/
├── antora-playbook.yml # production (aggregates sibling repos)
├── antora-playbook-local.yml
└── package.json
| Path | Description |
|---|---|
apps/main |
Organization website (SolidStart) |
docs/ |
Hub Antora component (SOS + org pages) |
docs-tools/ |
Shared tools component landing (CLI/library manuals register as modules) |
@sos/grammar |
Grammar definitions for parsing SOS syntax |
@sos/validator-core |
Core validation logic for SOS compliance |
This hub uses the antora-diagram-engines packages Facto documents — not custom renderers:
| Diagram source | Renderer | Package / extension |
|---|---|---|
AsciiDoc [source,mermaid] (and .mermaid-client roles) |
Client Mermaid in the browser | @antora-supplemental/mermaid-client |
| PlantUML and other Kroki diagram types in AsciiDoc | Build-time bake via Kroki | asciidoctor-kroki (kroki-server-url, kroki-fetch-diagram) |
| Baked SVG + client Mermaid hosts | Lightbox / zoom UI | @antora-supplemental/diagram-lightbox |
image::…[.themed-svg] committed figures (e.g. shell-architecture) |
Pre-generated adaptive/host SVGs in the product repo (mermaid-cli + @dev-centr/mermaid-svg-css-vars); runtime recolor via @dev-centr/themed-svg |
Bake freshness: shell-architecture pnpm diagrams:check / pnpm test (not re-run from this hub) |
Playbook attrs: mermaid-client: '', mermaid-client-mode: client. Supplemental UI loads mermaid-client-* and diagram-lightbox-* partials after SoftNav (Facto stack demo pattern).
Hub diagram CI (pnpm diagrams:check:all): sync/check vendored themed-svg runtime, static dark-mode text audit on committed adaptive SVGs (no mermaid-cli / Puppeteer), and verifier unit tests. Antora build runs verify-themed-svg-dark-mode as warnings on catalog SVGs.
Mermaid → SVG bake is not validated here. Hub Actions do not run mermaid-cli or Puppeteer. If you change .mmd or theme manifests in a product repo, run that repo’s pnpm diagrams / pnpm diagrams:check on a developer machine before merge (shell-architecture diagrams guide). See CONTRIBUTING.md.
git clone https://github.com/openshellorg/docs.git
cd docs
pnpm install# Apps / packages
pnpm dev
pnpm build
# Docs (Antora)
pnpm docs
# or local sibling checkouts:
pnpm docs:local
# Themed SVG / diagram audits (hub static checks only; no upstream mermaid-cli)
pnpm diagrams:check:allPublished docs: https://docs.opensh.org/
Org site: https://openshellorg.github.io/
See CHANGELOG.adoc.
Open Shell Org — openshell@devcentr.org
Project Link: https://github.com/openshellorg/docs