Skip to content

chore: initialize the docs site repository - #1

Merged
pimlock merged 7 commits into
mainfrom
chore/init-repo/pimlock
Nov 18, 2026
Merged

pimlock merged 7 commits into
mainfrom
chore/init-repo/pimlock

Conversation

@pimlock

@pimlock pimlock commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Sets up the docs site: a Starlight site assembled from the docs of several repositories, starting with two docsets.

Docset Repository Versions
OpenShell NVIDIA/OpenShell docs/ dev (main), 0.1.9, 0.1.8, 0.1.7
Go SDK ai-openshell/sdk-go docs/src/ dev (main), 0.1.8, 0.1.7

Changes

  • Assembler, site, and theme, configured by sources.yml.
  • Site workflow: builds on pull requests, and builds and deploys to GitHub Pages from main.
  • Broken links in fetched versions are warnings, so one repository can't block the site. They are errors in a --local checkout.
  • mise.toml pins Node.js and adds tasks: build, serve, test, lint, format, typecheck.
  • Biome for formatting and linting, astro check for type checking, and node:test unit tests. All run in CI.
  • LICENSE, SECURITY.md, CONTRIBUTING.md, AGENTS.md, and Dependabot.
  • SPDX headers on every file, checked in CI with ai-openshell/workflows spdx-check.

Testing

  • mise run build, mise run test, mise run lint, and mise run typecheck pass; CI is green.
  • Served the built site locally and checked the docs, Go SDK, and /latest/ pages.

Set up the multi-repo docs site from the docs prototype, with the
OpenShell core and Go SDK docsets. Node.js is pinned with mise. Adds
LICENSE, SECURITY.md, CONTRIBUTING.md, AGENTS.md and Dependabot from
the OpenShell repository template.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Broken links in a source repo's dev branch failed the whole site build,
so one repo could block the site. Fetched versions now only warn, and
CI shows each warning as an annotation. Previews, --local checkouts and
this repo's own pages stay strict, so each repo still catches its own
problems.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@pimlock
pimlock force-pushed the chore/init-repo/pimlock branch from 0f6bdb9 to b8a3e34 Compare November 17, 2026 23:07
Add Biome for formatting and linting (warnings fail) and astro check
for type checking, both run in CI. Format the code, fix the lint
findings, and type Astro.locals so components no longer use any. Header
imports Starlight's public components instead of virtual modules.

The built site is unchanged apart from formatting.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Remove the reusable preview workflow, the assembler's preview mode
(remote versions from links.json, inbound link guard, fragment layout,
diff view) and links.json, which only previews read. Previews are
tracked in #2 and will ship separately.

The built pages are unchanged.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Unit-test the docset.yml, Fern and mdBook readers, and run the
assembler end to end against two local git repos: link rewriting,
repo:// links, redirects, warnings for fetched versions, and errors for
a --local checkout. Tests use node:test, run offline, and run in CI.

Add --sources so the assembler can read another sources.yml.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Add SPDX-License-Identifier: Apache-2.0 to every file, with .license
sidecars for JSON and images, and run ai-openshell/workflows' spdx-check
on pull requests. The CNCF logos are third-party and excluded.

The mdBook reader now drops a page's H1 after leading comments, such as
an SPDX header, and the readers and site sync skip .license sidecars so
they are never published.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@pimlock
pimlock merged commit 7d2982d into main Nov 18, 2026
4 checks passed
@pimlock
pimlock deleted the chore/init-repo/pimlock branch November 18, 2026 18:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants