From d5fc1f3942d90196923f667409b21ac746bca1b0 Mon Sep 17 00:00:00 2001 From: Kanav Jain Date: Mon, 12 Oct 2026 20:48:23 -0500 Subject: [PATCH] feat(docs): publish the docs site from this repository at /refract/ The site was built and deployed by the refract-docs repository at https://refract-org.github.io/refract-docs/, so since #37 an edit to apps/docs published nowhere. docs-deploy.yml now builds apps/docs on pushes to main and publishes it to this repository's Pages site, https://refract-org.github.io/refract/. build.mjs's BASE and SITE_URL default to the new address, so canonical URLs, og:url, JSON-LD and the sitemap use it; the docs tests expect it. docs.js's fallback base pointed at /refract-docs/ and is updated with it. The README, CONTRIBUTING, ARCHITECTURE, package READMEs, apps' READMEs and the "Full docs" line `refract analyze` prints point at the new site. The old address keeps working through a redirect-only site published from refract-docs, in a separate PR there. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docs-deploy.yml | 51 +++++++++++++++++++++++++++++++ AGENTS.md | 2 +- ARCHITECTURE.md | 2 +- CHANGELOG.md | 1 + CONTRIBUTING.md | 2 +- README.md | 2 +- apps/docs/AGENTS.md | 2 +- apps/docs/README.md | 4 +-- apps/docs/assets/docs.js | 2 +- apps/docs/build.mjs | 4 +-- apps/docs/package.json | 2 +- apps/docs/tests/links.test.ts | 40 ++++++++++++------------ apps/docs/tests/seo.test.ts | 4 +-- apps/ui/README.md | 2 +- docs/repositories.md | 16 ++++++---- packages/analyzers/README.md | 2 +- packages/cli/README.md | 2 +- packages/cli/src/index.ts | 2 +- packages/eval/README.md | 2 +- packages/evidence-graph/README.md | 2 +- packages/ingestion/README.md | 2 +- packages/persistence/README.md | 2 +- 22 files changed, 103 insertions(+), 47 deletions(-) create mode 100644 .github/workflows/docs-deploy.yml diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..0a6a170 --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,51 @@ +name: Deploy docs site + +# Publishes apps/docs to this repository's GitHub Pages site, +# https://refract-org.github.io/refract/. The site used to deploy from the +# refract-docs repository at /refract-docs/; that address now serves a +# redirect-only site pointing each old page at its new one. +on: + push: + branches: [main] + paths: + - apps/docs/** + - .github/workflows/docs-deploy.yml + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: oven-sh/setup-bun@v2 + with: + bun-version: "1.3.14" + - uses: actions/setup-node@v6 + with: + node-version: 22 + - run: bun install --frozen-lockfile + - run: bun run build + working-directory: apps/docs + - uses: actions/configure-pages@v6 + - uses: actions/upload-pages-artifact@v5 + with: + path: apps/docs/dist + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deploy.outputs.page_url }} + steps: + - id: deploy + uses: actions/deploy-pages@v5 diff --git a/AGENTS.md b/AGENTS.md index b98347b..1f0733f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ bun run lint # biome lint packages/ - **packages/cli**: CLI tool (`refract` command) - **packages/persistence**: SQLite storage (bun:sqlite) - **packages/eval**: Evaluation harness -- **apps/docs**: Public documentation site (CC-BY-4.0). Private workspace; `bun run lint|test|build` from its directory; CI is `docs-site.yml`. +- **apps/docs**: Public documentation site (CC-BY-4.0), published to https://refract-org.github.io/refract/ by `docs-deploy.yml`. Private workspace; `bun run lint|test|build` from its directory; CI is `docs-site.yml`. - **apps/ui**: Browser-only file viewer. Private workspace that imports evidence-graph's event types as types only; CI is `viewer.yml`, which also runs on evidence-graph and `docs/examples` changes. The root `bun run test` and `bun run lint` cover `packages/` only; each app has its own `AGENTS.md`. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3202c3a..69ec290 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -75,7 +75,7 @@ On Wikipedia the ground truth is RFC closures and ArbCom decisions; on fandom wikis it's talk-page-archived consensus with revision links to the exact edit that implemented the decision. -![Architecture Data Flow](https://refract-org.github.io/refract-docs/architecture-flow.svg) +![Architecture Data Flow](https://refract-org.github.io/refract/architecture-flow.svg) ## Data Flow (Text) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1332409..a439420 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ - **The docs site and the viewer are checked in CI.** Since #37 imported them into `apps/docs` and `apps/ui`, nothing ran their lint, tests or builds: their workflows sat under `apps/*/.github`, which GitHub does not read, and the root suite excludes `apps/`. `docs-site.yml` and `viewer.yml` now run each app's checks, path-filtered and separate from the engine gate. The viewer's also runs when `packages/evidence-graph` or `docs/examples` change. ### Changed +- **The docs site moved to https://refract-org.github.io/refract/.** It is built and published from `apps/docs` by `docs-deploy.yml`, so a change to the engine and to its documentation can land in one PR. Every page under the old address, https://refract-org.github.io/refract-docs/, redirects to the same page at the new one, and the old images stay where they were. Canonical URLs, Open Graph tags and the sitemap use the new address, as do the "Next steps" that `refract analyze` prints and the package READMEs. - **The apps use the monorepo's tooling.** Their own lockfiles (two `bun.lock`, one `package-lock.json`), `.husky` hooks, `mise.toml` and `prepare: husky` scripts are removed; the root lockfile, hook and toolchain cover them, and each app's `.lintstagedrc.json` still applies to its files. Their `package.json` repository and issue links point at this repository. ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69a28b5..ff00ec6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ 2. **Run the gate**: `bun run build && bun run typecheck && bun run test` — all must pass before you start 3. **Pick a task**: [Good first issues](https://github.com/refract-org/refract/labels/good%20first%20issue) are scoped for new contributors. The [workqueue](.github/workqueue/) has `ready` tasks. 4. **Read the architecture**: [ARCHITECTURE.md](./ARCHITECTURE.md) — 5 minutes, saves hours of wrong turns -5. **Build a custom analyzer**: [Tutorial](https://refract-org.github.io/refract-docs/tutorials/custom-analyzer/) steps through the full cycle +5. **Build a custom analyzer**: [Tutorial](https://refract-org.github.io/refract/tutorials/custom-analyzer/) steps through the full cycle 6. **Run `bun run ci` before opening a PR**: build + lint + typecheck + boundaries + test. All must pass. ### What packages need what diff --git a/README.md b/README.md index f3611d4..0c29603 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ These build on the core engine: | Project | Purpose | |---------|---------| -| [Docs site](./apps/docs) | Public documentation site — [integrations](https://refract-org.github.io/refract-docs/integrations/), quickstart, CLI, SDK, tutorials | +| [Docs site](./apps/docs) | Public documentation site — [integrations](https://refract-org.github.io/refract/integrations/), quickstart, CLI, SDK, tutorials | | [Viewer](./apps/ui) | Browser-only file viewer — load JSONL, render timelines, diffs, citations | | [Demo data](./demo-data) | Local datasets; the [offline walkthrough](./docs/recipes.md#try-the-offline-walkthrough) uses a fictional library history | | [refract-py](https://github.com/refract-org/refract-py) | Python adapter — calls the CLI and returns dataclasses or DataFrames | diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md index 5ed4e40..50bf36d 100644 --- a/apps/docs/AGENTS.md +++ b/apps/docs/AGENTS.md @@ -17,7 +17,7 @@ bun run test # Vitest (verifies docs compile) - **Linter/Formatter:** Biome - **Tests:** Vitest - **Pre-commit:** the repository root's Husky hook runs lint-staged, which uses this directory's `.lintstagedrc.json` -- **CI:** `.github/workflows/docs-site.yml` at the repository root +- **CI:** `.github/workflows/docs-site.yml` at the repository root; `docs-deploy.yml` publishes `main` to https://refract-org.github.io/refract/ - **Commit style:** Conventional Commits ## Verification diff --git a/apps/docs/README.md b/apps/docs/README.md index 88a2cc7..72636cd 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -4,7 +4,7 @@ Public documentation for [Refract](https://github.com/refract-org/refract), a de --- -**Live at:** [refract-org.github.io/refract-docs](https://refract-org.github.io/refract-docs/) +**Live at:** [refract-org.github.io/refract](https://refract-org.github.io/refract/) ## Quick start @@ -12,7 +12,7 @@ Public documentation for [Refract](https://github.com/refract-org/refract), a de npx @refract-org/cli analyze "Earth" --depth brief ``` -See [quickstart](https://refract-org.github.io/refract-docs/quickstart/) for a full walkthrough. +See [quickstart](https://refract-org.github.io/refract/quickstart/) for a full walkthrough. ## Packages diff --git a/apps/docs/assets/docs.js b/apps/docs/assets/docs.js index 307b50c..a4a8708 100644 --- a/apps/docs/assets/docs.js +++ b/apps/docs/assets/docs.js @@ -113,7 +113,7 @@ let selectedIndex = -1; let currentResults = []; // Base path retrieved from global config -const BASE = window.REFRACT_BASE || "/refract-docs/"; +const BASE = window.REFRACT_BASE || "/refract/"; async function loadSearchIndex() { if (indexLoaded) return; diff --git a/apps/docs/build.mjs b/apps/docs/build.mjs index 63567bb..5a9401b 100644 --- a/apps/docs/build.mjs +++ b/apps/docs/build.mjs @@ -10,11 +10,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url)); const DOCS_DIR = join(__dirname, "docs"); const DIST_DIR = join(__dirname, "dist"); const ASSETS_DIR = join(__dirname, "assets"); -const BASE = process.env.BASE || "/refract-docs/"; +const BASE = process.env.BASE || "/refract/"; // Absolute address of the published site. Canonical URLs, og:url, JSON-LD // and the sitemap point here even when BASE is overridden for a local build. const SITE_URL = ( - process.env.SITE_URL || "https://refract-org.github.io/refract-docs/" + process.env.SITE_URL || "https://refract-org.github.io/refract/" ).replace(/\/?$/, "/"); const SITE_NAME = "Refract"; const SITE_DESCRIPTION = diff --git a/apps/docs/package.json b/apps/docs/package.json index 2d45019..6e86197 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -10,7 +10,7 @@ "url": "git+https://github.com/refract-org/refract.git", "directory": "apps/docs" }, - "homepage": "https://refract-org.github.io/refract-docs/", + "homepage": "https://refract-org.github.io/refract/", "bugs": { "url": "https://github.com/refract-org/refract/issues" }, diff --git a/apps/docs/tests/links.test.ts b/apps/docs/tests/links.test.ts index 88cfa7a..d567c1d 100644 --- a/apps/docs/tests/links.test.ts +++ b/apps/docs/tests/links.test.ts @@ -10,7 +10,7 @@ import { rewriteLink } from "../build.mjs"; const ROOT_DIR = resolve(__dirname, ".."); const DOCS_DIR = join(ROOT_DIR, "docs"); const DIST_DIR = join(ROOT_DIR, "dist"); -const SITE_BASE = "/refract-docs"; +const SITE_BASE = "/refract"; const SITE_URL = `https://refract-org.github.io${SITE_BASE}/`; const execFileAsync = promisify(execFile); @@ -213,7 +213,7 @@ function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } -// The URL path a link in a built page points at ("/refract-docs/cli/"), or +// The URL path a link in a built page points at ("/refract/cli/"), or // null for an external link or a same-page anchor. Absolute links to the // published site, such as the canonical URL, count as internal. function sitePathOf(sourceFile: string, href: string): string | null { @@ -364,45 +364,45 @@ describe("Generated site links", async () => { describe("rewriteLink", () => { it.each([ - ["cli", "", "/refract-docs/cli/"], - ["./cli", "", "/refract-docs/cli/"], - ["cli/", "", "/refract-docs/cli/"], - ["cli.md", "", "/refract-docs/cli/"], + ["cli", "", "/refract/cli/"], + ["./cli", "", "/refract/cli/"], + ["cli/", "", "/refract/cli/"], + ["cli.md", "", "/refract/cli/"], [ "schema#version-compatibility", "", - "/refract-docs/schema/#version-compatibility", + "/refract/schema/#version-compatibility", ], [ "schema.md#version-compatibility", "", - "/refract-docs/schema/#version-compatibility", + "/refract/schema/#version-compatibility", ], - ["tutorials/refract-ui", "", "/refract-docs/tutorials/refract-ui/"], - ["fandom-canon.md", "tutorials", "/refract-docs/tutorials/fandom-canon/"], - ["../analytics.md", "tutorials", "/refract-docs/analytics/"], - ["../index.md", "tutorials", "/refract-docs/"], - ["index.md", "", "/refract-docs/"], - ["./", "", "/refract-docs/"], - ["/quickstart", "tutorials", "/refract-docs/quickstart/"], - ["cli?x=1", "", "/refract-docs/cli/?x=1"], + ["tutorials/refract-ui", "", "/refract/tutorials/refract-ui/"], + ["fandom-canon.md", "tutorials", "/refract/tutorials/fandom-canon/"], + ["../analytics.md", "tutorials", "/refract/analytics/"], + ["../index.md", "tutorials", "/refract/"], + ["index.md", "", "/refract/"], + ["./", "", "/refract/"], + ["/quickstart", "tutorials", "/refract/quickstart/"], + ["cli?x=1", "", "/refract/cli/?x=1"], ])("links %s (from docs/%s) to the page URL %s", (href, dir, expected) => { expect(rewriteLink(href, dir)).toBe(expected); }); it.each([ - ["mcp-sequence.svg", "", "/refract-docs/mcp-sequence.svg"], + ["mcp-sequence.svg", "", "/refract/mcp-sequence.svg"], [ "assets/refract-ui-screenshot.png", "", - "/refract-docs/assets/refract-ui-screenshot.png", + "/refract/assets/refract-ui-screenshot.png", ], [ "notebooks/model-evaluation.ipynb", "", - "/refract-docs/notebooks/model-evaluation.ipynb", + "/refract/notebooks/model-evaluation.ipynb", ], - ["../boundary.svg", "tutorials", "/refract-docs/boundary.svg"], + ["../boundary.svg", "tutorials", "/refract/boundary.svg"], ])( "leaves the asset link %s (from docs/%s) without a slash", (href, dir, expected) => { diff --git a/apps/docs/tests/seo.test.ts b/apps/docs/tests/seo.test.ts index f2d627f..08769b6 100644 --- a/apps/docs/tests/seo.test.ts +++ b/apps/docs/tests/seo.test.ts @@ -15,7 +15,7 @@ import { const ROOT_DIR = resolve(__dirname, ".."); const DIST_DIR = join(ROOT_DIR, "dist"); -const SITE_URL = "https://refract-org.github.io/refract-docs/"; +const SITE_URL = "https://refract-org.github.io/refract/"; const SITE_DESCRIPTION = "A deterministic observation engine for revision histories. It reads a page's edits and emits a typed event for each change."; // Pages that use the site description: the home page by design, and pages with @@ -366,7 +366,7 @@ describe("social card", () => { const png = renderSocialCard({ name: "Refract", description, - address: "refract-org.github.io/refract-docs", + address: "refract-org.github.io/refract", }); expect(pngSize(Buffer.from(png))).toEqual({ width: 1200, height: 630 }); }); diff --git a/apps/ui/README.md b/apps/ui/README.md index c84b6da..c707b3e 100644 --- a/apps/ui/README.md +++ b/apps/ui/README.md @@ -53,4 +53,4 @@ Then drag `bitcoin-events.jsonl` onto the Refract UI upload zone. --- -[Refract Engine](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract-docs/) · [npm](https://www.npmjs.com/org/refract-org) +[Refract Engine](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/org/refract-org) diff --git a/docs/repositories.md b/docs/repositories.md index 9d205a8..e4cc58a 100644 --- a/docs/repositories.md +++ b/docs/repositories.md @@ -13,10 +13,12 @@ adapter provide optional ways to consume its output. | `refract` `apps/ui/` | Browser-only file viewer | NDJSON events; event types imported from `@refract-org/evidence-graph` | `viewer.yml`: `bun run lint`, `bun run test` (with the engine contract), `bun run build` | | [refract-py](https://github.com/refract-org/refract-py) | Python subprocess adapter and notebook integrations | CLI flags and NDJSON output | `hatch test`, `hatch build` | -The docs site still deploys from the [refract-docs](https://github.com/refract-org/refract-docs) -repository, whose source was imported into `apps/docs/` with its history; the -[refract-ui](https://github.com/refract-org/refract-ui) source was imported into -`apps/ui/` the same way. Neither old repository has changed since the import. +The docs site deploys from this repository (`docs-deploy.yml`) to +. The [refract-docs](https://github.com/refract-org/refract-docs) +and [refract-ui](https://github.com/refract-org/refract-ui) sources were imported +into `apps/docs/` and `apps/ui/` with their history. refract-docs now publishes +only a redirect site, which sends each `/refract-docs/` page to the same page +under `/refract/`. This inventory was checked on 2026-10-12. The organization has no current `refract-labs` or `refract-demo-data` repository. Datasets live in `demo-data/`; @@ -78,8 +80,10 @@ tested; repository consolidation does not require a simultaneous toolchain move. tutorial and asset paths. Build and preview the complete site before changing deployment. Preserve `/refract-docs/` URLs through an explicit redirect or deployment arrangement, including deep links, search, sitemap, and images. - *Status:* history imported (#37); lint, tests and build run in `docs-site.yml`. - Deployment has not moved, and reference pages are not yet mapped to `docs/`. + *Status:* history imported (#37); lint, tests and build run in `docs-site.yml`; + `docs-deploy.yml` publishes to `/refract/`, and refract-docs serves a page at + every old path that redirects to the new one, plus copies of the old images + and a catch-all for anything else. Reference pages are not yet mapped to `docs/`. 2. **Move the viewer.** Import its history under `apps/ui/`, preserve its license, and keep its browser-only operation. Replace independently maintained event lists with a checked schema fixture or type-only adapter; diff --git a/packages/analyzers/README.md b/packages/analyzers/README.md index 729075d..d02e7fa 100644 --- a/packages/analyzers/README.md +++ b/packages/analyzers/README.md @@ -70,4 +70,4 @@ const ids = events.map((e) => createEventIdentity(e)); For everything `refract analyze` prints, add `buildPageMoveEvents(windowPageMoves(...))` before and `correlateTalkRevisions(revisions, talkRevisions)` after `buildRevisionEvents`, then annotate all of them together. -[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/analyzers) +[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/analyzers) diff --git a/packages/cli/README.md b/packages/cli/README.md index aa6b772..286d433 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -45,4 +45,4 @@ refract diff --wiki-a https://starwars.fandom.com/api.php --wiki-b https://memor refract eval ``` -[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/cli) +[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/cli) diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 99fc4ce..67c4dcb 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -202,7 +202,7 @@ analyzeCmd.action(async (page, opts) => { ); console.log(dim(` Monitor for changes → refract cron pages.txt --interval 24 --notify-slack`)); console.log(dim(` Connect an AI → refract mcp`)); - console.log(dim(` Full docs → https://refract-org.github.io/refract-docs`)); + console.log(dim(` Full docs → https://refract-org.github.io/refract/`)); } }); diff --git a/packages/eval/README.md b/packages/eval/README.md index 4d409f8..dc3b0db 100644 --- a/packages/eval/README.md +++ b/packages/eval/README.md @@ -28,4 +28,4 @@ bun add @refract-org/eval import { createEvalHarness, validateAgainstGroundTruth } from "@refract-org/eval"; ``` -[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/eval) +[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/eval) diff --git a/packages/evidence-graph/README.md b/packages/evidence-graph/README.md index 0cac30a..9917cd3 100644 --- a/packages/evidence-graph/README.md +++ b/packages/evidence-graph/README.md @@ -37,4 +37,4 @@ import type { EvidenceEvent, Revision } from "@refract-org/evidence-graph"; import { createClaimIdentity, createVerificationBundle } from "@refract-org/evidence-graph"; ``` -[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/evidence-graph) +[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/evidence-graph) diff --git a/packages/ingestion/README.md b/packages/ingestion/README.md index 65842c2..0c6fd80 100644 --- a/packages/ingestion/README.md +++ b/packages/ingestion/README.md @@ -35,4 +35,4 @@ import { GitRevisionSource, MediaWikiClient, RateLimiter } from "@refract-org/in import type { RevisionFetcher, RevisionOptions } from "@refract-org/ingestion"; ``` -[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/ingestion) +[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/ingestion) diff --git a/packages/persistence/README.md b/packages/persistence/README.md index 8b2f9d8..2218619 100644 --- a/packages/persistence/README.md +++ b/packages/persistence/README.md @@ -21,4 +21,4 @@ import { Persistence } from "@refract-org/persistence"; import type { PersistenceAdapter, PersistenceConfig } from "@refract-org/persistence"; ``` -[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) +[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/)