From e382532d47e46a1036d0220f077d2409ddaa7e31 Mon Sep 17 00:00:00 2001 From: James Yang Date: Mon, 3 Aug 2026 23:03:31 -0400 Subject: [PATCH 1/3] ci(docs): fail PRs on broken Mintlify internal links Add apps/docs check-links (mintlify broken-links) and run it in the existing CI workflow. Assert a clean report because mintlify 4.2.x can exit 0 even when broken links are printed. Fixes #1365 --- .github/workflows/ci.yml | 7 +++++++ apps/docs/package.json | 3 ++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 80600ae50..462d489e4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,3 +31,10 @@ jobs: - name: Run Biome CI (format & lint on changed files) run: bunx biome ci --changed --since=origin/main --no-errors-on-unmatched + + # mintlify@4.2.x may exit 0 even when it prints broken links + - name: Check docs for broken internal links + working-directory: apps/docs + run: | + set -o pipefail + bun run check-links 2>&1 | tee /dev/stderr | grep -q "no broken links found" diff --git a/apps/docs/package.json b/apps/docs/package.json index a3aff8c29..e443f967c 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -6,7 +6,8 @@ "portless": { "name": "docs.dev.supermemory", "script": "dev:app", "appPort": 3003 }, "scripts": { "dev": "portless", - "dev:app": "bunx mintlify@latest dev --no-open --port 3003" + "dev:app": "bunx mintlify@latest dev --no-open --port 3003", + "check-links": "mintlify broken-links" }, "devDependencies": { "@types/bun": "latest", From f1af9303c561a58ddd9c0b7f7292670ab4d151f0 Mon Sep 17 00:00:00 2001 From: James Yang Date: Wed, 2 Sep 2026 19:50:08 -0400 Subject: [PATCH 2/3] ci(docs): isolate mintlify so broken-link CI survives the monorepo Hoisted mintlify crashes with a React invalid-hook-call. Run it via isolated bunx, and only on docs changes. --- .github/workflows/ci.yml | 13 ++++++++++++- apps/docs/package.json | 2 +- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 72acc7790..0dc1a059b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -107,8 +107,19 @@ jobs: - name: Run Biome CI (format & lint on changed files) run: bunx biome ci --changed --since=origin/main --no-errors-on-unmatched - # mintlify@4.2.x may exit 0 even when it prints broken links + - name: Detect docs changes + id: docs-changes + run: | + if git diff --quiet "${{ github.event.pull_request.base.sha }}" HEAD -- apps/docs; then + echo "docs=false" >> "$GITHUB_OUTPUT" + else + echo "docs=true" >> "$GITHUB_OUTPUT" + fi + + # Isolated bunx avoids the monorepo React/ink hook crash from hoisted mintlify. + # mintlify@4.2.x may exit 0 even when it prints broken links. - name: Check docs for broken internal links + if: steps.docs-changes.outputs.docs == 'true' working-directory: apps/docs run: | set -o pipefail diff --git a/apps/docs/package.json b/apps/docs/package.json index e443f967c..e42425a96 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -7,7 +7,7 @@ "scripts": { "dev": "portless", "dev:app": "bunx mintlify@latest dev --no-open --port 3003", - "check-links": "mintlify broken-links" + "check-links": "bunx --bun mintlify@4.2.112 broken-links" }, "devDependencies": { "@types/bun": "latest", From c9b829f98b281f56f7952742b88ec5a3dad542da Mon Sep 17 00:00:00 2001 From: James Yang Date: Wed, 2 Sep 2026 20:09:41 -0400 Subject: [PATCH 3/3] fix(docs): point backfill guide at real ingest API pages Mintlify only sees static files, so the invented OpenAPI child paths were failing the broken-link check. --- apps/docs/ingestion/batch-ingest-historical-data.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/ingestion/batch-ingest-historical-data.mdx b/apps/docs/ingestion/batch-ingest-historical-data.mdx index 17ff4e1bd..10230dd96 100644 --- a/apps/docs/ingestion/batch-ingest-historical-data.mdx +++ b/apps/docs/ingestion/batch-ingest-historical-data.mdx @@ -15,7 +15,7 @@ Use `POST /v3/documents/batch` to backfill exports, emails, messages, or other d Backfill dated content by setting `documentDate` on each document, sorting the source records oldest to newest, and sending them in batches. Each request can contain up to 600 documents. -**Endpoint:** [`POST /v3/documents/batch`](/api-reference/ingest/batch-add-documents) +**Endpoint:** [`POST /v3/documents/batch`](/api-reference/ingest) @@ -93,7 +93,7 @@ def backfill_historical_data(source_documents: list[dict[str, str]]) -> None: ## Optional: wait for processing to finish -**Endpoint:** [`GET /v3/documents/{id}`](/api-reference/documents/get-document) +**Endpoint:** [`GET /v3/documents/{id}`](/api-reference/ingest) The batch endpoint returns after accepting the documents. If a later step depends on completed memory generation, poll the returned document IDs until both `status` and `dreamingStatus` are `done`.