Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# SPDX-License-Identifier: Apache-2.0

version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
groups:
npm-minor-and-patch:
update-types: ["minor", "patch"]

- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
79 changes: 79 additions & 0 deletions .github/workflows/site.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# SPDX-License-Identifier: Apache-2.0

# Build the whole site from sources.yml and publish it to GitHub Pages.
#
# Runs on pull requests (build only), on changes to main, hourly (to pick up
# new commits on each source's dev branch), and on demand. A source repo can
# trigger it with repository_dispatch when it pushes main or a release tag.
name: Site

on:
pull_request:
push:
branches: [main]
schedule:
- cron: "17 * * * *"
workflow_dispatch:
repository_dispatch:
types: [docs-source-updated]

permissions:
contents: read

concurrency:
group: site-${{ github.event_name == 'pull_request' && github.ref || 'main' }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
# Checkouts are keyed by commit, so old entries stay valid forever.
- uses: actions/cache@v4
with:
path: .cache/sources
key: sources-${{ github.run_id }}
restore-keys: sources-
- run: npm ci
- name: Check formatting and lint
run: npm run lint
- name: Unit tests
run: npm test
- name: Assemble (fetches each source at its ref)
run: node assembler/assemble.mjs --base /${{ github.event.repository.name }}/
- name: Type-check
run: npm run typecheck
- name: Build site
run: npm run site
env:
BASE_PATH: /${{ github.event.repository.name }}/
SITE_URL: https://${{ github.repository_owner }}.github.io
- name: Record the commits this build used
run: |
echo '### Sources' >> "$GITHUB_STEP_SUMMARY"
echo '| Version | Ref | Commit | Format |' >> "$GITHUB_STEP_SUMMARY"
echo '|---|---|---|---|' >> "$GITHUB_STEP_SUMMARY"
node -e 'for (const [k, v] of Object.entries(require("./build/assembled/sources.lock.json"))) console.log(`| ${k} | ${v.repo}@${v.ref} | ${v.sha.slice(0, 12)} | ${v.format} |`)' >> "$GITHUB_STEP_SUMMARY"
cp build/assembled/sources.lock.json site/dist/
- uses: actions/upload-pages-artifact@v3
if: github.event_name != 'pull_request'
with:
path: site/dist

deploy:
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deploy.outputs.page_url }}
steps:
- id: deploy
uses: actions/deploy-pages@v4
28 changes: 28 additions & 0 deletions .github/workflows/spdx.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# SPDX-License-Identifier: Apache-2.0

# Every tracked file needs SPDX-License-Identifier: Apache-2.0 in its first 10
# lines, or in a <file>.license sidecar for files that can't hold a comment.
name: SPDX

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
spdx:
name: spdx
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ai-openshell/workflows/spdx-check@0b051efd25c3f7319634fed863d2e03e1bd55d7b # main
with:
include: "*"
# LICENSE is the license text; the CNCF logos are third-party artwork.
exclude: "LICENSE site/static/cncf/*"
11 changes: 11 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# SPDX-License-Identifier: Apache-2.0

node_modules/
.cache/
build/
site/dist/
site/.astro/
site/src/content/docs/
site/src/generated/
site/public/
site/src/styles/tokens.css
35 changes: 35 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Agent Instructions

This repository builds the OpenShell docs site from the docs of several
repositories, listed in `sources.yml`. It holds no page content. See
[CONTRIBUTING.md](CONTRIBUTING.md) for setup and tasks.

## Commands

- `mise run build` fetches every source and builds the site. Broken links in
fetched versions only warn; fix them in the source repository. Broken links
in a `--local` checkout fail the build.
- `mise run serve` serves the built site.
- `mise run lint` checks formatting and lint (Biome, warnings fail); run it
before every commit. `mise run format` fixes formatting.
- `mise run test` runs the assembler's tests (`node:test`, in `test/`). The
assembler test builds small local git repos from `test/fixtures/`, so it
needs no network.
- `mise run typecheck` type-checks the site, including `.astro` files.

## Conventions

- `build/`, `.cache/`, and the generated paths under `site/` (see `.gitignore`)
are build outputs. Never edit or commit them.
- Every file needs `SPDX-License-Identifier: Apache-2.0` in a comment in its
first 10 lines (front matter in `.mdx` and `.astro`), or a `<file>.license`
sidecar for JSON and images. CI checks it.

## Commits

- Use Conventional Commits and sign off every commit (`--signoff`).
- Never mention Claude or any AI agent in commits, pull request descriptions, or
issues (no author attribution, no Co-Authored-By, no "Generated with"
footers).
45 changes: 45 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Contributing to the OpenShell docs site

This repository holds the site build, theme, and navigation. Page content lives
in each source repository; change it there. See the [README](README.md) for
how the build works.

## Setup

The site needs Node.js, pinned in [`mise.toml`](mise.toml), and git. Install
[mise](https://mise.jdx.dev/), then:

```shell
mise install
mise run install
```

| Task | What it does |
| ------------------- | -------------------------------------------------------- |
| `mise run build` | Fetch every source and build the site into `site/dist` |
| `mise run serve` | Serve the built site at <http://127.0.0.1:4410/docs/> |
| `mise run assemble` | Fetch and assemble the sources without building the site |
| `mise run test` | Run the assembler's unit tests |
| `mise run lint` | Check formatting and lint with [Biome](https://biomejs.dev/) |
| `mise run format` | Format the code and apply safe lint fixes |
| `mise run typecheck` | Assemble the sources and type-check the site with `astro check` |

To build against a local checkout instead of a source's `dev` branch, run
`node assembler/assemble.mjs --base /docs/ --local core=../OpenShell` before
`BASE_PATH=/docs/ npm run site`. Broken links in a local checkout fail the
build; in fetched versions they only warn.

## Commits and pull requests

- Use [Conventional Commits](https://www.conventionalcommits.org/):
`<type>(<scope>): <description>`.
- Sign off every commit (`git commit --signoff`) for the [Developer Certificate
of Origin](https://developercertificate.org/).
- Every change goes through a pull request. Pull requests are squash-merged.
- Every file needs the license line `SPDX-License-Identifier: Apache-2.0` in
a comment in its first 10 lines; the `SPDX` workflow checks it. In `.mdx`
and `.astro` files, put it in the front matter. A file that can't hold a
comment, such as JSON or an image, gets a `<file>.license` file containing
the line instead.
Loading
Loading