diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..c5d2b54 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,16 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + groups: + astro: + patterns: + - "astro" + - "@astrojs/*" + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..e863c9a --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,22 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v5 + with: + node-version: 24 + cache: npm + - run: npm ci + - run: npm run build diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e0852e9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,83 @@ +# Contributing to the Ordo documentation + +Thanks for considering a contribution. This repository holds the source for the Ordo documentation site at `docs.ordo.ephyrasoftware.com`. The site itself is built with [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) docs theme. + +## What kinds of contributions are welcome + +- Typo and grammar fixes +- Clarifications where a page is confusing or ambiguous +- Missing details (a flag, an option, an edge case) that would have saved you time +- New examples or recipes for things Ordo supports +- New pages that fit the existing information architecture (see below) + +For larger changes — new sections, restructured navigation, significant rewrites — please open an issue first so the direction can be agreed before you invest the time. Small fixes can go straight to a pull request. + +If something on the docs site is wrong because Ordo itself behaves differently than documented, file an issue here describing what you observed and what the docs led you to expect. We will route it to the right place. + +## Local development + +```sh +git clone https://github.com/EphyraSoftware/ordo-docs +cd ordo-docs +npm install +npm run dev +``` + +The dev server runs at `http://localhost:4321` with hot reload. To produce a production build: + +```sh +npm run build +``` + +The output is written to `dist/`. CI runs the same build on every pull request. + +## Information architecture + +The site has four top-level sections: + +| Section | Audience and intent | +|---|---| +| Getting Started | A first-time operator following a guided walkthrough | +| Concepts | Short prose pages tying terminology to behaviour | +| Reference | CLI, API, state file format, and configuration — exhaustive, lookup-oriented | +| Architecture | Operator-facing explanation of how the orchestrator and agents fit together | + +When adding a page, decide which section it belongs in based on intent: + +- **Walkthrough or worked example** → Getting Started +- **"What does X mean?"** → Concepts +- **"What flags does this command accept?"** → Reference +- **"How does this fit together?"** → Architecture + +If a page does not fit any section, that is a signal to discuss the structure in an issue rather than to add a new section directly. + +## Voice and style + +Documentation in this repository aims to be: + +- **Concise.** Short paragraphs. One idea per paragraph. Cut words that do not change the meaning. +- **Direct.** Tell the reader what to do or what something means. Avoid hedging like "you might want to consider". +- **Present tense, second person.** "Run `ordo init`." rather than "You will need to run `ordo init`." +- **Scannable.** Use headings, lists, and tables when they help. Do not use them for decoration. +- **British English** for original prose. American English from upstream sources (error messages, third-party tool names) stays as it appears in those sources. + +Code samples should be runnable as written, with placeholders clearly marked (``, ``). + +## Sidebar configuration + +The sidebar is configured in [`astro.config.mjs`](./astro.config.mjs). Each top-level section is currently a single page; as subpages are added, convert the section's entry from a single link into a group with `autogenerate: { directory: '
' }` (Starlight will pick up files automatically) or hand-listed `items` (when ordering matters). + +## Pull request conventions + +- Branch names use kebab-case and reflect the change: `fix/typo-in-tags-page`, `docs/add-drift-recipe`. +- Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `docs:`, `fix:`, `chore:`, `refactor:`, etc. The PR title should also follow this convention. +- For amendments after review, use fixup commits (`git commit --fixup=`) and autosquash before merge rather than amending in place. +- Do not add `Co-Authored-By` lines to commits. + +## What CI checks + +Every pull request runs `npm ci` followed by `npm run build`. The build must pass before a PR can merge. Broken internal links, invalid frontmatter, and missing referenced content all fail the build. + +## License + +By contributing, you agree that your contributions are licensed under the same terms as this repository. diff --git a/README.md b/README.md index f59550b..586d1b5 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,4 @@ The sidebar is configured in `astro.config.mjs`. As subpages are added under eac ## Contributing -Spotted a typo, a confusing page, or a missing detail? Pull requests are welcome. Small fixes do not need a prior issue — open a PR directly. For larger changes, open an issue first so the direction can be agreed before you invest the time. - -The Ordo project itself lives at [`EphyraSoftware/ordo`](https://github.com/EphyraSoftware/ordo). +Spotted a typo, a confusing page, or a missing detail? See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Small fixes can go straight to a pull request; larger changes start with an issue. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 780f99d..7cf3205 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,10 +8,6 @@ hero: - text: Get started link: /getting-started/ icon: right-arrow - - text: View on GitHub - link: https://github.com/EphyraSoftware/ordo - icon: external - variant: minimal --- import { Card, CardGrid } from '@astrojs/starlight/components';