docs(ci): add Mintlify preview, docsync guard, and broken-links workflow
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site (Node 22 handling modeled on the Gas City wrapper). - test/docsync: Go guard keeping docs/ and docs.json in exact correspondence — every nav entry has a file, every page is in the nav (tiny stub allowlist for paths released bd binaries print), published pages use root-relative extensionless links that resolve, and engdocs/ plus curated root markdown keep exact GitHub-style paths. Wired into make check-docs. - .github/workflows/docs-mintlify.yml: docsync + baseline-aware mint broken-links check on PRs touching docs/**. - Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six mirrored files now live once in the Mintlify site; the committed Docusaurus mirrors stay frozen so the parallel-run site keeps building. - Repoint inbound links to moved docs across README, guides, examples, npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md pointer stub (bd's agent templates print that path). Runtime strings in cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print old paths — covered by stubs, flagged in the PR.
This commit is contained in:
parent
4ea6fa3ac0
commit
3198395a32
42 changed files with 717 additions and 289 deletions
136
.github/scripts/docs-render-check.sh
vendored
Executable file
136
.github/scripts/docs-render-check.sh
vendored
Executable file
|
|
@ -0,0 +1,136 @@
|
|||
#!/usr/bin/env bash
|
||||
#
|
||||
# docs-render-check.sh — baseline-aware Mintlify broken-link check for CI.
|
||||
#
|
||||
# Runs `mint broken-links` on the HEAD docs tree. When the HEAD has broken
|
||||
# page links, materializes the BASE docs tree (via git archive) and reports
|
||||
# only NET-NEW breakage — links that the PR introduced, not pre-existing ones.
|
||||
# Static-asset refs (.png/.svg/.jpg/.gif) are excluded: mint over-reports
|
||||
# in-tree images the published build serves fine.
|
||||
#
|
||||
# Usage:
|
||||
# docs-render-check.sh [<base-ref>]
|
||||
#
|
||||
# <base-ref> The base branch/sha to compare against (default: origin/main).
|
||||
# Enables baseline-aware net-new detection.
|
||||
#
|
||||
# Exit codes:
|
||||
# 0 — no net-new page-link regressions
|
||||
# 1 — net-new page-link regressions found; details on stdout
|
||||
#
|
||||
# Requires: git, npx (Node.js), jq
|
||||
#
|
||||
set -euo pipefail
|
||||
|
||||
DOCS_DIR="docs"
|
||||
DOCS_CONFIG="$DOCS_DIR/docs.json"
|
||||
BASE_REF="${1:-origin/main}"
|
||||
MINT_CMD="${MINT_CMD:-npx --yes mint@latest}"
|
||||
|
||||
WORK_TMP="$(mktemp -d)"
|
||||
trap 'rm -rf "$WORK_TMP"' EXIT
|
||||
|
||||
# Verify we have a Mintlify docs tree.
|
||||
if [[ ! -f "$DOCS_CONFIG" ]]; then
|
||||
echo "docs-render-check: no docs/docs.json found — skipping" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# --- extract_page_links <mint-output-file> -----------------------------------
|
||||
# Parse `mint broken-links` output lines. Each broken link looks like:
|
||||
# [broken-links] tutorials/01-beads.md -> /tutorials/01-beads.md
|
||||
# or
|
||||
# ✗ /tutorials/01-beads.md
|
||||
# We capture only page links (no static-asset extensions).
|
||||
ASSET_EXTS='\.png$|\.svg$|\.jpg$|\.jpeg$|\.gif$|\.ico$|\.webp$|\.woff2?$|\.ttf$|\.eot$'
|
||||
|
||||
extract_page_links() {
|
||||
local file="$1"
|
||||
grep -oE '[^ ]+\.[a-z]+$|/[^ ]+' "$file" 2>/dev/null \
|
||||
| grep -vE "$ASSET_EXTS" \
|
||||
| sort -u || true
|
||||
}
|
||||
|
||||
# Alternative simpler extraction: just lines with the broken-links marker.
|
||||
parse_mint_broken_links() {
|
||||
local file="$1"
|
||||
# mint outputs lines like: " ✗ /path/to/page" or " ✗ page-slug"
|
||||
# or with indentation. Grab any token that looks like a link (starts with /).
|
||||
grep -E '✗|broken|BROKEN|error|ERROR' "$file" 2>/dev/null \
|
||||
| grep -oE '[/][^ )]+' \
|
||||
| grep -vE "$ASSET_EXTS" \
|
||||
| sort -u || true
|
||||
}
|
||||
|
||||
# --- run_mint <docs-root> <output-file> → exit code -------------------------
|
||||
run_mint() {
|
||||
local root="$1"
|
||||
local out="$2"
|
||||
cd "$root"
|
||||
if $MINT_CMD broken-links >"$out" 2>&1; then
|
||||
cd - >/dev/null
|
||||
return 0
|
||||
fi
|
||||
cd - >/dev/null
|
||||
return 1
|
||||
}
|
||||
|
||||
HEAD_OUT="$WORK_TMP/head-mint.txt"
|
||||
BASE_OUT="$WORK_TMP/base-mint.txt"
|
||||
BASE_TREE="$WORK_TMP/base-docs"
|
||||
|
||||
# --- HEAD check --------------------------------------------------------------
|
||||
HEAD_EXIT=0
|
||||
run_mint "." "$HEAD_OUT" || HEAD_EXIT=$?
|
||||
|
||||
if [[ $HEAD_EXIT -eq 0 ]]; then
|
||||
echo "docs-render-check: no broken links in HEAD — PASS" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
HEAD_LINKS="$WORK_TMP/head-links.txt"
|
||||
parse_mint_broken_links "$HEAD_OUT" | sort -u >"$HEAD_LINKS"
|
||||
|
||||
if [[ ! -s "$HEAD_LINKS" ]]; then
|
||||
# mint exited non-zero but no links we care about. Pass.
|
||||
echo "docs-render-check: mint non-zero but no page-link regressions detected — PASS" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# --- BASE check (baseline-aware) --------------------------------------------
|
||||
mkdir -p "$BASE_TREE"
|
||||
if git archive "$BASE_REF" -- "$DOCS_DIR" 2>/dev/null | tar -x -C "$BASE_TREE"; then
|
||||
BASE_EXIT=0
|
||||
run_mint "$BASE_TREE" "$BASE_OUT" || BASE_EXIT=$?
|
||||
BASE_LINKS="$WORK_TMP/base-links.txt"
|
||||
parse_mint_broken_links "$BASE_OUT" | sort -u >"$BASE_LINKS"
|
||||
# Net-new = in HEAD but NOT in BASE.
|
||||
NEW_LINKS="$WORK_TMP/new-links.txt"
|
||||
comm -23 "$HEAD_LINKS" "$BASE_LINKS" >"$NEW_LINKS"
|
||||
else
|
||||
echo "docs-render-check: could not materialize base tree from $BASE_REF — checking HEAD only" >&2
|
||||
cp "$HEAD_LINKS" "$WORK_TMP/new-links.txt"
|
||||
NEW_LINKS="$WORK_TMP/new-links.txt"
|
||||
fi
|
||||
|
||||
if [[ ! -s "$NEW_LINKS" ]]; then
|
||||
echo "docs-render-check: broken links exist but none are net-new — PASS (pre-existing baseline)" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# --- NET-NEW regressions found — fail with explanation --------------
|
||||
echo ""
|
||||
echo "::error::docs-render-check: net-new broken Mintlify page links detected"
|
||||
echo ""
|
||||
echo "The following page links are newly broken by this PR:"
|
||||
while IFS= read -r link; do
|
||||
echo " $link"
|
||||
done <"$NEW_LINKS"
|
||||
echo ""
|
||||
echo "──────────────────────────────────────────────────────────────────────────"
|
||||
echo "docs/ is authored for the Mintlify site (the beads Mintlify site),"
|
||||
echo "not for direct GitHub viewing. These paths/links are intentional —"
|
||||
echo "please don't reformat them for GitHub. If something is genuinely broken"
|
||||
echo "on the live site, note it in the PR and we'll fix it Mintlify-side."
|
||||
echo "──────────────────────────────────────────────────────────────────────────"
|
||||
exit 1
|
||||
53
.github/workflows/docs-mintlify.yml
vendored
Normal file
53
.github/workflows/docs-mintlify.yml
vendored
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
name: Docs (Mintlify) checks
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened, ready_for_review]
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'test/docsync/**'
|
||||
- 'mint.sh'
|
||||
- '.github/scripts/docs-render-check.sh'
|
||||
- '.github/workflows/docs-mintlify.yml'
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: docs-mintlify-${{ github.event.pull_request.number }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
docsync:
|
||||
name: Docs nav/link sync (go test ./test/docsync)
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event.pull_request.draft == false
|
||||
steps:
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
|
||||
with:
|
||||
go-version-file: 'go.mod'
|
||||
|
||||
- name: Run docsync guard
|
||||
run: go test ./test/docsync
|
||||
|
||||
broken-links:
|
||||
name: Mintlify broken-links (baseline-aware)
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event.pull_request.draft == false
|
||||
steps:
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
||||
with:
|
||||
node-version: 22
|
||||
|
||||
- name: Run baseline-aware broken-link check
|
||||
env:
|
||||
BASE_REF: origin/${{ github.base_ref }}
|
||||
run: .github/scripts/docs-render-check.sh "$BASE_REF"
|
||||
8
.github/workflows/pr.yml
vendored
8
.github/workflows/pr.yml
vendored
|
|
@ -171,14 +171,6 @@ jobs:
|
|||
./scripts/check-doc-flags.sh ./bd
|
||||
./scripts/check-doc-freshness.sh
|
||||
|
||||
# Website doc mirrors (website/docs/... and, when applicable,
|
||||
# website/versioned_docs/version-<latest>/...) are a pure text
|
||||
# transform of their docs/ sources, so this needs no bd build and no
|
||||
# merge-base attribution: it just fails if scripts/sync-website-docs.sh
|
||||
# produces any diff against the committed mirrors.
|
||||
- name: Validate website doc mirrors
|
||||
run: ./scripts/check-website-docs-drift.sh
|
||||
|
||||
# When the drift check fails, it writes the exact regenerated-docs fix
|
||||
# (produced with CI's canonical build) so contributors can apply it with
|
||||
# `git apply` instead of reproducing CI's environment locally. The
|
||||
|
|
|
|||
|
|
@ -106,9 +106,9 @@ bd hooks install
|
|||
|
||||
**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No export/import round-trip needed for normal sync.
|
||||
|
||||
**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
|
||||
**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/reference/protected-branches.md](docs/reference/protected-branches.md).
|
||||
|
||||
**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md).
|
||||
**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/reference/advanced.md](docs/reference/advanced.md).
|
||||
|
||||
**Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution.
|
||||
|
||||
|
|
@ -509,7 +509,7 @@ still works as a one-off, shell-scoped override.
|
|||
|
||||
- Check existing issues: `bd list`
|
||||
- Look at recent commits: `git log --oneline -20`
|
||||
- Read the docs: README.md, ADVANCED.md, docs/CONFIG.md
|
||||
- Read the docs: README.md, ADVANCED.md, docs/reference/configuration.md
|
||||
- Create an issue if unsure: `bd create "Question: ..." -t task -p 2`
|
||||
|
||||
## Important Files
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Federation Setup Guide
|
||||
|
||||
The canonical federation guide is [docs/FEDERATION.md](docs/FEDERATION.md).
|
||||
The canonical federation guide is [docs/multi-agent/federation.md](docs/multi-agent/federation.md).
|
||||
|
||||
This root-level file remains only as a stable pointer for existing links
|
||||
(website quickstart pages, `llms-full.txt`).
|
||||
|
|
|
|||
5
Makefile
5
Makefile
|
|
@ -252,6 +252,11 @@ check-docs:
|
|||
@CGO_ENABLED=0 go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o $(BUILD_DIR)/bd ./cmd/bd
|
||||
@./scripts/check-doc-flags.sh ./bd
|
||||
@./scripts/check-doc-freshness.sh
|
||||
@go test ./test/docsync
|
||||
|
||||
# Live preview of the Mintlify docs site (docs/) at http://localhost:3000
|
||||
docs-dev:
|
||||
./mint.sh dev
|
||||
|
||||
# Ensure -short is not used as an implicit CI tier boundary.
|
||||
check-testing-short:
|
||||
|
|
|
|||
16
README.md
16
README.md
|
|
@ -32,7 +32,7 @@ bd setup factory # Factory.ai Droid - creates/updates AGENTS.md
|
|||
|
||||
**Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.
|
||||
|
||||
`bd init` creates or updates `AGENTS.md` by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass `--skip-agents` or `--stealth`. Use `bd setup --list` to see supported integrations, including `bd setup codex`, `bd setup factory`, `bd setup claude`, `bd setup mux`, `bd setup cursor`, and more. See [Agent and IDE setup](docs/SETUP.md).
|
||||
`bd init` creates or updates `AGENTS.md` by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass `--skip-agents` or `--stealth`. Use `bd setup --list` to see supported integrations, including `bd setup codex`, `bd setup factory`, `bd setup claude`, `bd setup mux`, `bd setup cursor`, and more. See [Agent and IDE setup](docs/getting-started/ide-setup.md).
|
||||
|
||||
Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun `bd init`/`bd setup`, or custom instruction files. In those cases, run `bd onboard` and paste the printed snippet into the file your agent reads.
|
||||
|
||||
|
|
@ -90,9 +90,9 @@ brew install beads # macOS / Linux (recommended)
|
|||
npm install -g @beads/bd # Node.js users
|
||||
```
|
||||
|
||||
**Other methods:** [install script](docs/INSTALLING.md#quick-install-script-all-platforms) | [go install](docs/INSTALLING.md#a-note-on-go-install-capability) | [from source](docs/INSTALLING.md#build-dependencies-contributors-only) | [Windows](docs/INSTALLING.md#windows-11) | [Arch AUR](docs/INSTALLING.md#linux)
|
||||
**Other methods:** [install script](docs/getting-started/installation.md#quick-install-script-all-platforms) | [go install](docs/getting-started/installation.md#a-note-on-go-install-capability) | [from source](docs/getting-started/installation.md#build-dependencies-contributors-only) | [Windows](docs/getting-started/installation.md#windows-11) | [Arch AUR](docs/getting-started/installation.md#linux)
|
||||
|
||||
**Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/INSTALLING.md](docs/INSTALLING.md) for complete installation guide.
|
||||
**Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/getting-started/installation.md](docs/getting-started/installation.md) for complete installation guide.
|
||||
|
||||
**Upgrading?** Replacing the binary is not always the whole story. Short
|
||||
version: sync remote-backed databases with your current `bd`, back up with
|
||||
|
|
@ -102,7 +102,7 @@ migration on a remote-backed database, exactly one designated clone runs
|
|||
`bd migrate --force` and `bd dolt push`; other clones install the new binary
|
||||
and run `bd bootstrap`. See the full
|
||||
[upgrade guide](https://gastownhall.github.io/beads/docs/getting-started/upgrading)
|
||||
or [docs/INSTALLING.md](docs/INSTALLING.md#updating-bd).
|
||||
or [docs/getting-started/installation.md](docs/getting-started/installation.md#updating-bd).
|
||||
|
||||
### Security And Verification
|
||||
|
||||
|
|
@ -112,7 +112,7 @@ The install scripts verify release checksums before install. For manual installs
|
|||
|
||||
On macOS, `scripts/install.sh` preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via `BEADS_INSTALL_RESIGN_MACOS=1`.
|
||||
|
||||
See [docs/ANTIVIRUS.md](docs/ANTIVIRUS.md) for Windows AV false-positive guidance and verification workflow.
|
||||
See [docs/reference/antivirus.md](docs/reference/antivirus.md) for Windows AV false-positive guidance and verification workflow.
|
||||
|
||||
## 💾 Storage Modes
|
||||
|
||||
|
|
@ -213,9 +213,9 @@ branches, commit history, working-set state, or non-issue tables. Use
|
|||
|
||||
## 🌐 Community Tools
|
||||
|
||||
See [docs/COMMUNITY_TOOLS.md](docs/COMMUNITY_TOOLS.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.
|
||||
See [docs/community-tools.md](docs/community-tools.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.
|
||||
|
||||
See [docs/RELATED_PROJECTS.md](docs/RELATED_PROJECTS.md) for adjacent or complementary projects that solve different problems in the same neighborhood.
|
||||
See [docs/related-projects.md](docs/related-projects.md) for adjacent or complementary projects that solve different problems in the same neighborhood.
|
||||
|
||||
## 🚀 Git-Free Usage
|
||||
|
||||
|
|
@ -250,5 +250,5 @@ For daemon mode without git, use `bd daemon start --local`
|
|||
|
||||
## 📝 Documentation
|
||||
|
||||
* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/INSTALLING.md) | [Sync Concepts](docs/SYNC_CONCEPTS.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/COPILOT_CLI_INTEGRATION.md) | [Copilot VS Code MCP](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
|
||||
* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md)
|
||||
* [](https://deepwiki.com/gastownhall/beads)
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ Once version 1.0 is released, we will support the latest major version and one p
|
|||
2. **Review before sharing** - Check issue content before sharing project details
|
||||
3. **Use private repos** - If your issues contain proprietary information, use private git repositories
|
||||
4. **Validate git hooks** - If using automated export/import hooks, review them for safety
|
||||
5. **Regular updates** - Keep bd updated with your package manager, or re-run the install script from [docs/INSTALLING.md](docs/INSTALLING.md).
|
||||
5. **Regular updates** - Keep bd updated with your package manager, or re-run the install script from [docs/getting-started/installation.md](docs/getting-started/installation.md).
|
||||
|
||||
## Known Limitations
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
// Package main implements the bd CLI state management commands.
|
||||
// These commands provide convenient access to the labels-as-state pattern
|
||||
// documented in docs/LABELS.md.
|
||||
// documented in docs/core-concepts/labels.md.
|
||||
package main
|
||||
|
||||
import (
|
||||
|
|
|
|||
6
docs/SYNC_CONCEPTS.md
Normal file
6
docs/SYNC_CONCEPTS.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Sync Concepts
|
||||
|
||||
This guide moved to [core-concepts/sync-concepts.md](core-concepts/sync-concepts.md)
|
||||
as part of the Mintlify docs site under `docs/`. This pointer stays because
|
||||
`bd init`'s agent instruction templates link to `docs/SYNC_CONCEPTS.md` on
|
||||
GitHub.
|
||||
|
|
@ -69,8 +69,8 @@ irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
|
|||
brew upgrade beads
|
||||
```
|
||||
|
||||
<!-- Canonical Homebrew tap-migration snippet. The installation page links
|
||||
here; docs/INSTALLING.md mirrors this block. Keep all three in sync. -->
|
||||
{/* Canonical Homebrew tap-migration snippet. The installation page links
|
||||
here; keep the two in sync. */}
|
||||
If you still have the old tap formula installed as `bd`, switch to the
|
||||
Homebrew core formula:
|
||||
|
||||
|
|
@ -227,7 +227,7 @@ lost — that is why step 1 publishes everything first. If a clone was instead
|
|||
migrated independently and `bd dolt pull` later fails with `cannot merge because
|
||||
table dependencies has different primary keys in its common ancestor`, the
|
||||
schema has already forked — follow the recovery playbook:
|
||||
[RECOVERY.md#pk-fork-refused](https://github.com/gastownhall/beads/blob/main/docs/RECOVERY.md#pk-fork-refused).
|
||||
[the pk-fork-refused runbook](/recovery/init-safety#pk-fork-refused).
|
||||
|
||||
<Note>
|
||||
In **server mode**, `bd doctor` adds a migration-content-skew check that flags a
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ bd setup copilot --remove
|
|||
- `plugins/beads/copilot_manifest.go` - Embedded manifest source used by `bd setup copilot`
|
||||
- `internal/recipes/recipes.go` - Lightweight `copilot` recipe definition
|
||||
- `internal/recipes/template.go` - Static Copilot instructions template used by `bd setup`
|
||||
- `docs/COPILOT_INTEGRATION.md` - VS Code MCP integration
|
||||
- [GitHub Copilot integration](/integrations/github-copilot) - VS Code MCP integration
|
||||
|
||||
## References
|
||||
|
||||
|
|
|
|||
|
|
@ -86,8 +86,8 @@ generation.
|
|||
- **AGENTS.md** - Complete workflow and development guide (READ THIS!)
|
||||
- **README.md** - User-facing documentation
|
||||
- **ADVANCED.md** - Advanced features (rename, merge, compaction)
|
||||
- **docs/LABELS.md** - Complete label system guide
|
||||
- **docs/CONFIG.md** - Configuration system
|
||||
- **docs/core-concepts/labels.md** - Complete label system guide
|
||||
- **docs/reference/configuration.md** - Configuration system
|
||||
|
||||
## When Adding Features
|
||||
|
||||
|
|
|
|||
|
|
@ -142,5 +142,5 @@ This generates the tables above and shows adaptive scaling strategy for any thre
|
|||
|
||||
## Related Documentation
|
||||
|
||||
- [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) - Configuration and usage guide
|
||||
- [CONFIG.md](CONFIG.md) - All configuration options
|
||||
- [ADAPTIVE_IDS.md](../docs/core-concepts/adaptive-ids.md) - Configuration and usage guide
|
||||
- [CONFIG.md](../docs/reference/configuration.md) - All configuration options
|
||||
|
|
|
|||
|
|
@ -142,8 +142,8 @@ accordingly:
|
|||
Creates `~/.beads-planning/` and configures routing.
|
||||
|
||||
5. **Documentation**:
|
||||
- `docs/ROUTING.md` - Auto-routing mechanics
|
||||
- `docs/MULTI_REPO_MIGRATION.md` - Contributor workflow guide
|
||||
- `docs/multi-agent/routing.md` - Auto-routing mechanics
|
||||
- `docs/multi-agent/multi-repo-migration.md` - Contributor workflow guide
|
||||
|
||||
### What's NOT Implemented (Gaps)
|
||||
|
||||
|
|
|
|||
|
|
@ -134,7 +134,7 @@ The dolthub maintainers have made clear the upstream default will not flip: *"We
|
|||
|
||||
### How `go install` is handled now
|
||||
|
||||
Two supported modes, documented in [INSTALLING.md](INSTALLING.md):
|
||||
Two supported modes, documented in [INSTALLING.md](../docs/getting-started/installation.md):
|
||||
|
||||
1. **`CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest`** produces a **server-mode-only** binary. Works on any Go-capable box with no C compiler. Users must run an external `dolt sql-server` and use `bd init --server`.
|
||||
|
||||
|
|
@ -172,6 +172,6 @@ No fork, no replace directive, no upstream patch required. The tradeoff is that
|
|||
|
||||
## See Also
|
||||
|
||||
- [INSTALLING.md](INSTALLING.md) -- user-facing build dependency docs
|
||||
- [DOLT.md](DOLT.md) -- embedded Dolt architecture
|
||||
- [INSTALLING.md](../docs/getting-started/installation.md) -- user-facing build dependency docs
|
||||
- [DOLT.md](../docs/architecture/dolt.md) -- embedded Dolt architecture
|
||||
- [CONTRIBUTING.md](../CONTRIBUTING.md) -- contributor guidelines
|
||||
|
|
|
|||
|
|
@ -87,6 +87,6 @@ When adding support for a new tracker or extending an existing one:
|
|||
## Related Documents
|
||||
|
||||
- [Project Charter](PROJECT_CHARTER.md) - Overall product scope and boundaries
|
||||
- [CLI Reference](CLI_REFERENCE.md) — Full command documentation
|
||||
- [CLI Reference](../docs/CLI_REFERENCE.md) — Full command documentation
|
||||
- [SECURITY.md](../SECURITY.md) — Security considerations for tracker tokens
|
||||
- [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute new integrations
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This document describes internal implementation details of bd, with particular focus on concurrency guarantees and data consistency.
|
||||
|
||||
For the overall architecture (data model, sync mechanism, component overview), see [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
For the overall architecture (data model, sync mechanism, component overview), see [ARCHITECTURE.md](../docs/architecture/index.md).
|
||||
|
||||
## Auto-Flush Architecture
|
||||
|
||||
|
|
|
|||
|
|
@ -261,5 +261,5 @@ rm -rf /tmp/beads-bench-cache/
|
|||
## See Also
|
||||
|
||||
- [TESTING.md](TESTING.md) - General testing guide
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
|
||||
- [ARCHITECTURE.md](../docs/architecture/index.md) - System architecture
|
||||
- [INTERNALS.md](INTERNALS.md) - Implementation details
|
||||
|
|
|
|||
|
|
@ -110,7 +110,7 @@ absorb, transform, or reroute the useful part.
|
|||
## Related Documents
|
||||
|
||||
- [Integration Charter](INTEGRATION_CHARTER.md) - tracker integration scope
|
||||
- [Issue Metadata](METADATA.md) - metadata extension point
|
||||
- [Architecture](ARCHITECTURE.md) - data model and storage architecture
|
||||
- [Issue Metadata](../docs/core-concepts/metadata.md) - metadata extension point
|
||||
- [Architecture](../docs/architecture/index.md) - data model and storage architecture
|
||||
- [Maintainer PR Guidelines](../PR_MAINTAINER_GUIDELINES.md) - PR triage and
|
||||
contributor handling
|
||||
|
|
|
|||
|
|
@ -243,9 +243,9 @@ func TestSomething(t *testing.T) {
|
|||
|
||||
## Related Documentation
|
||||
|
||||
- [WORKTREES.md](WORKTREES.md) - Git worktree integration
|
||||
- [ROUTING.md](ROUTING.md) - Multi-repository routing
|
||||
- [CONFIG.md](CONFIG.md) - BEADS_DIR and environment variables
|
||||
- [WORKTREES.md](../docs/reference/worktrees.md) - Git worktree integration
|
||||
- [ROUTING.md](../docs/multi-agent/routing.md) - Multi-repository routing
|
||||
- [CONFIG.md](../docs/reference/configuration.md) - BEADS_DIR and environment variables
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
|
|
|
|||
|
|
@ -310,7 +310,7 @@ OTel SDK uses dot-notation internally. Prometheus-compatible backends (VictoriaM
|
|||
| `DOLT_REMOTE_USER` | Push/pull auth user |
|
||||
| `DOLT_REMOTE_PASSWORD` | Push/pull auth password |
|
||||
|
||||
> **Note**: Dolt-specific configuration variables are documented in [DOLT.md](../../DOLT.md) and are out of scope for OTEL design documentation.
|
||||
> **Note**: Dolt-specific configuration variables are documented in [DOLT.md](../../../docs/architecture/dolt.md) and are out of scope for OTEL design documentation.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -480,8 +480,8 @@ FROM dolt_conflicts;
|
|||
## Related Documentation
|
||||
|
||||
- [OTel Data Model](otel-data-model.md) — Complete event schema
|
||||
- [OBSERVABILITY.md](../../OBSERVABILITY.md) — Quick reference for metrics
|
||||
- [Dolt Backend](../../DOLT.md) — Dolt configuration and usage
|
||||
- [OBSERVABILITY.md](../../../docs/reference/observability.md) — Quick reference for metrics
|
||||
- [Dolt Backend](../../../docs/architecture/dolt.md) — Dolt configuration and usage
|
||||
- [Dolt Concurrency](../dolt-concurrency.md) — Concurrency model and transactions
|
||||
|
||||
## Backends Compatible with OTLP
|
||||
|
|
|
|||
|
|
@ -121,5 +121,5 @@ target was not persisted do not produce hooks.
|
|||
|
||||
## See Also
|
||||
|
||||
- [Graph Links](graph-links.md) - relates_to, duplicates, supersedes, replies_to
|
||||
- [CLI Reference](CLI_REFERENCE.md) - All commands
|
||||
- [Graph Links](../docs/core-concepts/graph-links.md) - relates_to, duplicates, supersedes, replies_to
|
||||
- [CLI Reference](../docs/CLI_REFERENCE.md) - All commands
|
||||
|
|
|
|||
|
|
@ -121,7 +121,7 @@ export BEADS_DOLT_SHARED_SERVER=1
|
|||
|
||||
Shared server state lives in `~/.beads/shared-server/` and uses port 3308 by default
|
||||
(avoiding conflict with the orchestrator on 3307). Each project's data remains isolated in its
|
||||
own database (named by project prefix). See [DOLT.md](../DOLT.md) for details.
|
||||
own database (named by project prefix). See [DOLT.md](../../docs/architecture/dolt.md) for details.
|
||||
|
||||
## Central Dolt Server (macOS)
|
||||
|
||||
|
|
@ -328,7 +328,7 @@ If upgrading from an older version that used SQLite:
|
|||
> scripts/migrate-jsonl-to-dolt.sh
|
||||
> ```
|
||||
>
|
||||
> See [Troubleshooting](../TROUBLESHOOTING.md#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration.
|
||||
> See [Troubleshooting](../../docs/reference/troubleshooting.md#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration.
|
||||
|
||||
### Option 2: Fresh Start
|
||||
|
||||
|
|
@ -484,7 +484,7 @@ federation:
|
|||
## Migrating Between Backends
|
||||
|
||||
Use `bd backup` to migrate data between embedded and server mode. Both
|
||||
directions preserve full Dolt commit history. See [DOLT.md](../DOLT.md#migrating-between-backends)
|
||||
directions preserve full Dolt commit history. See [DOLT.md](../../docs/architecture/dolt.md#migrating-between-backends)
|
||||
for step-by-step instructions.
|
||||
|
||||
**Quick reference:**
|
||||
|
|
@ -512,6 +512,6 @@ bd list
|
|||
|
||||
## See Also
|
||||
|
||||
- [DOLT.md](../DOLT.md) - Dolt backend overview, federation, and mode details
|
||||
- [Troubleshooting](../TROUBLESHOOTING.md) - General troubleshooting
|
||||
- [DOLT.md](../../docs/architecture/dolt.md) - Dolt backend overview, federation, and mode details
|
||||
- [Troubleshooting](../../docs/reference/troubleshooting.md) - General troubleshooting
|
||||
- [Dolt Documentation](https://docs.dolthub.com/) - Official Dolt docs
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This legacy example demonstrates how to extend SQLite-backed bd databases with custom tables for application-specific orchestration.
|
||||
|
||||
> **Note:** Custom SQLite table extensions are a legacy pattern. Current Dolt-backed beads workflows should prefer standalone integration tools that call `bd --json` commands or use `bd query` for SQL access. See [Extensible Database](../../docs/ADVANCED.md#extensible-database) for the current guidance.
|
||||
> **Note:** Custom SQLite table extensions are a legacy pattern. Current Dolt-backed beads workflows should prefer standalone integration tools that call `bd --json` commands or use `bd query` for SQL access. See [Extensible Database](../../docs/reference/advanced.md#extensible-database) for the current guidance.
|
||||
|
||||
## What This Example Shows
|
||||
|
||||
|
|
|
|||
|
|
@ -223,6 +223,6 @@ bd config set routing.default . # Default to current repo
|
|||
|
||||
## See Also
|
||||
|
||||
- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md)
|
||||
- [Multi-Repo Migration Guide](../../docs/multi-agent/multi-repo-migration.md)
|
||||
- [Team Workflow Example](../team-workflow/)
|
||||
- [Protected Branch Setup](../protected-branch/)
|
||||
|
|
|
|||
|
|
@ -484,7 +484,7 @@ For large projects, initial sync fetches all issues. Subsequent syncs are increm
|
|||
|
||||
## See Also
|
||||
|
||||
- [CONFIG.md](../../docs/CONFIG.md) - Full configuration documentation
|
||||
- [CONFIG.md](../../docs/reference/configuration.md) - Full configuration documentation
|
||||
- [Jira Sync](../../README.md) - Similar integration for Jira (`bd jira sync`)
|
||||
- [Linear GraphQL API](https://developers.linear.app/docs/graphql/working-with-the-graphql-api)
|
||||
|
||||
|
|
|
|||
|
|
@ -662,4 +662,4 @@ bd dep add bd-uat1 bd-review1 --type blocks
|
|||
- [Multi-Phase Development](../multi-phase-development/) - Organize work by phase
|
||||
- [Team Workflow](../team-workflow/) - Collaborate across personas
|
||||
- [Contributor Workflow](../contributor-workflow/) - External contributions
|
||||
- [Labels Documentation](../../docs/LABELS.md) - Label management guide
|
||||
- [Labels Documentation](../../docs/core-concepts/labels.md) - Label management guide
|
||||
|
|
|
|||
|
|
@ -274,6 +274,6 @@ jobs:
|
|||
|
||||
## See Also
|
||||
|
||||
- [docs/PROTECTED_BRANCHES.md](../../docs/PROTECTED_BRANCHES.md) - Complete guide
|
||||
- [docs/reference/protected-branches.md](../../docs/reference/protected-branches.md) - Complete guide
|
||||
- [AGENTS.md](../../AGENTS.md) - Agent integration instructions
|
||||
- [docs/QUICKSTART.md](../../docs/QUICKSTART.md) - `bd dolt push` / `bd dolt pull` usage
|
||||
|
|
|
|||
|
|
@ -368,7 +368,7 @@ bd sql "CALL dolt_conflicts_resolve('--ours')"
|
|||
bd dolt push
|
||||
```
|
||||
|
||||
See [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md) for details.
|
||||
See [GIT_INTEGRATION.md](../../docs/reference/git-integration.md) for details.
|
||||
|
||||
### Issue: Issues not syncing
|
||||
|
||||
|
|
@ -390,5 +390,5 @@ bd validate --checks=conflicts
|
|||
|
||||
- [Protected Branch Setup](../protected-branch/)
|
||||
- [Contributor Workflow](../contributor-workflow/)
|
||||
- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md)
|
||||
- [Git Integration Guide](../../docs/GIT_INTEGRATION.md)
|
||||
- [Multi-Repo Migration Guide](../../docs/multi-agent/multi-repo-migration.md)
|
||||
- [Git Integration Guide](../../docs/reference/git-integration.md)
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ import "strings"
|
|||
// AgentProfile represents the explicit policy profile that controls agent
|
||||
// git/commit authority (gh#3423, follow-up to #4220's PROFILE_VOCABULARY doc).
|
||||
//
|
||||
// See docs/SETUP.md "Policy Profiles" for the full description of each value.
|
||||
// See docs/getting-started/ide-setup.md "Policy Profiles" for the full description of each value.
|
||||
type AgentProfile string
|
||||
|
||||
const (
|
||||
|
|
|
|||
|
|
@ -209,7 +209,7 @@ func Initialize() error {
|
|||
|
||||
// Agent profile configuration (gh#3423, follow-up to #4220)
|
||||
// Explicit runtime knob for the policy profile (git/commit authority)
|
||||
// documented in docs/SETUP.md. `bd prime` uses this to select its
|
||||
// documented in docs/getting-started/ide-setup.md. `bd prime` uses this to select its
|
||||
// close-protocol wording. Values: conservative | minimal | team-maintainer.
|
||||
// Invalid values fall back to "conservative" (see GetAgentProfile).
|
||||
v.SetDefault("agent.profile", string(ProfileConservative))
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
// VictoriaLogs :9428 — future log storage
|
||||
// Grafana :9429 — dashboards
|
||||
//
|
||||
// See docs/OBSERVABILITY.md for the full reference.
|
||||
// See docs/reference/observability.md for the full reference.
|
||||
package telemetry
|
||||
|
||||
import (
|
||||
|
|
|
|||
62
mint.sh
Executable file
62
mint.sh
Executable file
|
|
@ -0,0 +1,62 @@
|
|||
#!/usr/bin/env bash
|
||||
# Local preview for the Mintlify docs site under docs/.
|
||||
# Usage: ./mint.sh [dev|broken-links|...] (defaults to dev)
|
||||
set -euo pipefail
|
||||
|
||||
repo_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
|
||||
docs_dir="$repo_dir/docs"
|
||||
args=("$@")
|
||||
if [[ ${#args[@]} -eq 0 ]]; then
|
||||
args=(dev)
|
||||
fi
|
||||
|
||||
node_major() {
|
||||
node -p 'process.versions.node.split(".")[0]' 2>/dev/null || true
|
||||
}
|
||||
|
||||
find_node22_bin() {
|
||||
local prefix
|
||||
for prefix in /opt/homebrew/opt/node@22 /usr/local/opt/node@22; do
|
||||
if [[ -x "$prefix/bin/node" ]]; then
|
||||
printf '%s/bin\n' "$prefix"
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
|
||||
if command -v brew >/dev/null 2>&1; then
|
||||
prefix=$(brew --prefix node@22 2>/dev/null || true)
|
||||
if [[ -n "$prefix" && -x "$prefix/bin/node" ]]; then
|
||||
printf '%s/bin\n' "$prefix"
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
|
||||
return 1
|
||||
}
|
||||
|
||||
major=$(node_major)
|
||||
if [[ "$major" =~ ^[0-9]+$ ]] && (( major < 25 )); then
|
||||
cd "$docs_dir"
|
||||
exec npx --yes mint@latest "${args[@]}"
|
||||
fi
|
||||
|
||||
if node22_bin=$(find_node22_bin); then
|
||||
export PATH="$node22_bin:$PATH"
|
||||
cd "$docs_dir"
|
||||
exec npx --yes mint@latest "${args[@]}"
|
||||
fi
|
||||
|
||||
cat >&2 <<EOF
|
||||
Mintlify does not support Node 25+.
|
||||
|
||||
Use Node 22 LTS to preview the docs. For example:
|
||||
nvm use 22
|
||||
fnm use 22
|
||||
volta install node@22
|
||||
|
||||
On macOS with Homebrew:
|
||||
brew install node@22
|
||||
cd "$repo_dir"
|
||||
PATH="/opt/homebrew/opt/node@22/bin:\$PATH" ./mint.sh dev
|
||||
EOF
|
||||
exit 1
|
||||
|
|
@ -101,9 +101,9 @@ For complete documentation, see the [beads GitHub repository](https://github.com
|
|||
|
||||
- [Complete README](https://github.com/gastownhall/beads#readme)
|
||||
- [Quick Start (documentation site)](https://gastownhall.github.io/beads/getting-started/quickstart) · [repo pointer](https://github.com/gastownhall/beads/blob/main/docs/QUICKSTART.md)
|
||||
- [Installation Guide](https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md)
|
||||
- [FAQ](https://github.com/gastownhall/beads/blob/main/docs/FAQ.md)
|
||||
- [Troubleshooting](https://github.com/gastownhall/beads/blob/main/docs/TROUBLESHOOTING.md)
|
||||
- [Installation Guide](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md)
|
||||
- [FAQ](https://github.com/gastownhall/beads/blob/main/docs/reference/faq.md)
|
||||
- [Troubleshooting](https://github.com/gastownhall/beads/blob/main/docs/reference/troubleshooting.md)
|
||||
|
||||
## Why npm Package vs WASM?
|
||||
|
||||
|
|
|
|||
|
|
@ -85,10 +85,10 @@ Multi-clone, multi-branch workflows:
|
|||
|
||||
- Hash-based IDs (`bd-abc`) eliminate collision across clones
|
||||
- Each clone syncs independently via git
|
||||
- See [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/WORKTREES.md) for comprehensive guide
|
||||
- See [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/reference/worktrees.md) for comprehensive guide
|
||||
|
||||
## External References
|
||||
|
||||
- **Official Docs**: [github.com/gastownhall/beads/docs](https://github.com/gastownhall/beads/tree/main/docs)
|
||||
- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/gastownhall/beads/blob/main/docs/PROTECTED_BRANCHES.md)
|
||||
- **Worktrees**: [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/WORKTREES.md)
|
||||
- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/gastownhall/beads/blob/main/docs/reference/protected-branches.md)
|
||||
- **Worktrees**: [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/reference/worktrees.md)
|
||||
|
|
|
|||
|
|
@ -255,7 +255,7 @@ This allows releases to work before a certificate is acquired.
|
|||
|
||||
Windows code signing helps reduce antivirus false positives that affect Go binaries.
|
||||
Kaspersky and other AV software commonly flag unsigned Go executables as potentially
|
||||
malicious due to heuristic detection. See `docs/ANTIVIRUS.md` for details.
|
||||
malicious due to heuristic detection. See `docs/reference/antivirus.md` for details.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,85 +0,0 @@
|
|||
#!/bin/bash
|
||||
# check-website-docs-drift.sh — Freshness check for committed website doc mirrors.
|
||||
#
|
||||
# scripts/sync-website-docs.sh regenerates the Docusaurus mirrors of selected
|
||||
# root docs (website/docs/..., and, when a versioned snapshot exists,
|
||||
# website/versioned_docs/version-<latest>/... plus
|
||||
# website/versioned_sidebars/version-<latest>-sidebars.json) from their
|
||||
# source files in docs/. Unlike the CLI reference docs, this mirroring is a
|
||||
# pure text transform of files already committed in this repo — no bd binary
|
||||
# build and no blame-scoped attribution across a merge-base is needed. The
|
||||
# check simply runs the sync script and fails if it produces any diff
|
||||
# (tracked or untracked), then restores the working tree so the check itself
|
||||
# is side-effect-free.
|
||||
#
|
||||
# Usage: check-website-docs-drift.sh
|
||||
|
||||
set -euo pipefail
|
||||
export LC_ALL=C
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
|
||||
cd "$PROJECT_ROOT"
|
||||
|
||||
# All paths sync-website-docs.sh can write to. Checked, backed up, diffed,
|
||||
# and restored as a set.
|
||||
CHECK_PATHS=(website/docs website/versioned_docs website/versioned_sidebars)
|
||||
|
||||
if [ -n "$(git status --porcelain -- "${CHECK_PATHS[@]}" 2>/dev/null)" ]; then
|
||||
echo "WARN: working tree has uncommitted changes under ${CHECK_PATHS[*]};"
|
||||
echo " this check compares against the working tree as-is and will"
|
||||
echo " restore it to its pre-check state on exit."
|
||||
fi
|
||||
|
||||
TMP_BACKUP="$(mktemp -d)"
|
||||
mkdir -p "$TMP_BACKUP/website"
|
||||
cp -Rf website/docs "$TMP_BACKUP/website/docs"
|
||||
if [ -d website/versioned_docs ]; then
|
||||
cp -Rf website/versioned_docs "$TMP_BACKUP/website/versioned_docs"
|
||||
fi
|
||||
if [ -d website/versioned_sidebars ]; then
|
||||
cp -Rf website/versioned_sidebars "$TMP_BACKUP/website/versioned_sidebars"
|
||||
fi
|
||||
|
||||
restore_tree() {
|
||||
rm -rf website/docs website/versioned_docs website/versioned_sidebars
|
||||
cp -Rf "$TMP_BACKUP/website/docs" website/docs
|
||||
if [ -d "$TMP_BACKUP/website/versioned_docs" ]; then
|
||||
cp -Rf "$TMP_BACKUP/website/versioned_docs" website/versioned_docs
|
||||
fi
|
||||
if [ -d "$TMP_BACKUP/website/versioned_sidebars" ]; then
|
||||
cp -Rf "$TMP_BACKUP/website/versioned_sidebars" website/versioned_sidebars
|
||||
fi
|
||||
rm -rf "$TMP_BACKUP"
|
||||
}
|
||||
trap restore_tree EXIT
|
||||
|
||||
"$SCRIPT_DIR/sync-website-docs.sh"
|
||||
|
||||
# git diff alone misses drift where sync-website-docs.sh recreates a mirror
|
||||
# file that isn't currently tracked (e.g. a committed mirror was deleted, or
|
||||
# a new sync target was never committed): the recreated file is untracked
|
||||
# and invisible to `git diff`. Treat any new untracked file under the
|
||||
# checked paths as drift too.
|
||||
UNTRACKED="$(git ls-files --others --exclude-standard -- "${CHECK_PATHS[@]}")"
|
||||
|
||||
if git diff --quiet -- "${CHECK_PATHS[@]}" && [ -z "$UNTRACKED" ]; then
|
||||
echo "PASS: committed website doc mirrors are fresh (sync-website-docs.sh produces no changes)."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "FAIL: website doc mirrors are out of sync with their source docs."
|
||||
echo "Run: ./scripts/sync-website-docs.sh"
|
||||
echo ""
|
||||
if ! git diff --quiet -- "${CHECK_PATHS[@]}"; then
|
||||
git diff --stat -- "${CHECK_PATHS[@]}" | sed 's/^/ /'
|
||||
echo ""
|
||||
git diff -- "${CHECK_PATHS[@]}" | sed -n '1,200p'
|
||||
fi
|
||||
if [ -n "$UNTRACKED" ]; then
|
||||
echo ""
|
||||
echo "New (untracked) mirror files sync-website-docs.sh produced:"
|
||||
echo "$UNTRACKED" | sed 's/^/ /'
|
||||
fi
|
||||
exit 1
|
||||
|
|
@ -25,18 +25,12 @@ generate_llms_full() {
|
|||
./scripts/generate-llms-full.sh
|
||||
}
|
||||
|
||||
sync_website_docs() {
|
||||
cd "$REPO_ROOT"
|
||||
./scripts/sync-website-docs.sh
|
||||
}
|
||||
|
||||
website_build() {
|
||||
cd "$WEBSITE_DIR"
|
||||
npm run build
|
||||
}
|
||||
|
||||
ci_time "website npm ci" -- website_npm_ci
|
||||
ci_time "sync website docs" -- sync_website_docs
|
||||
ci_time "website typecheck" -- website_typecheck
|
||||
ci_time "generate llms-full" -- generate_llms_full
|
||||
ci_time "website build" -- website_build
|
||||
|
|
|
|||
|
|
@ -470,7 +470,7 @@ verify_binary_has_cgo() {
|
|||
# Tries CGO_ENABLED=1 first for an embedded-capable binary. If that fails
|
||||
# (host lacks C toolchain or transitive Dolt deps' headers), falls back to
|
||||
# CGO_ENABLED=0 which yields a server-mode-only binary that still works on
|
||||
# any Go-capable box. See engdocs/ICU-POLICY.md and docs/INSTALLING.md.
|
||||
# any Go-capable box. See engdocs/ICU-POLICY.md and docs/getting-started/installation.md.
|
||||
install_with_go() {
|
||||
log_info "Installing bd using 'go install'..."
|
||||
|
||||
|
|
|
|||
|
|
@ -1,126 +0,0 @@
|
|||
#!/usr/bin/env bash
|
||||
# Mirror selected root documentation into the Docusaurus website tree.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
|
||||
write_doc() {
|
||||
local source="$1"
|
||||
local target="$2"
|
||||
local id="$3"
|
||||
local title="$4"
|
||||
local slug="$5"
|
||||
|
||||
if [[ ! -f "$source" ]]; then
|
||||
echo "missing source doc: $source" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mkdir -p "$(dirname "$target")"
|
||||
{
|
||||
cat <<EOF
|
||||
---
|
||||
id: $id
|
||||
title: $title
|
||||
slug: $slug
|
||||
---
|
||||
|
||||
EOF
|
||||
rewrite_links "$source"
|
||||
} > "$target"
|
||||
}
|
||||
|
||||
rewrite_links() {
|
||||
local source="$1"
|
||||
|
||||
case "${source#$REPO_ROOT/}" in
|
||||
docs/LABELS.md)
|
||||
sed \
|
||||
-e 's@](CLI_REFERENCE.md#state-labels-as-cache)@](/cli-reference/set-state)@g' \
|
||||
-e 's#](../README.md#](https://github.com/gastownhall/beads/blob/main/README.md#g' \
|
||||
-e 's#](../AGENTS.md#](https://github.com/gastownhall/beads/blob/main/AGENTS.md#g' \
|
||||
-e 's#](ADVANCED.md#](/reference/advanced#g' \
|
||||
"$source"
|
||||
;;
|
||||
docs/METADATA.md)
|
||||
sed \
|
||||
-e 's#](../engdocs/PROJECT_CHARTER.md#](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#g' \
|
||||
"$source"
|
||||
;;
|
||||
*)
|
||||
cat "$source"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
doc_specs=(
|
||||
"docs/SYNC_CONCEPTS.md|website/docs/core-concepts/sync-concepts.md|sync-concepts|Sync Concepts|/core-concepts/sync-concepts"
|
||||
"docs/LABELS.md|website/docs/core-concepts/labels.md|labels|Labels|/core-concepts/labels"
|
||||
"docs/METADATA.md|website/docs/core-concepts/metadata.md|metadata|Issue Metadata|/core-concepts/metadata"
|
||||
"docs/UNINSTALLING.md|website/docs/recovery/uninstalling.md|uninstalling|Uninstalling|/recovery/uninstalling"
|
||||
"docs/ANTIVIRUS.md|website/docs/reference/antivirus.md|antivirus|Antivirus False Positives|/reference/antivirus"
|
||||
"docs/COMMUNITY_TOOLS.md|website/docs/community-tools.md|community-tools|Community Tools|/community-tools"
|
||||
)
|
||||
|
||||
for spec in "${doc_specs[@]}"; do
|
||||
IFS='|' read -r source target id title slug <<<"$spec"
|
||||
write_doc \
|
||||
"$REPO_ROOT/$source" \
|
||||
"$REPO_ROOT/$target" \
|
||||
"$id" \
|
||||
"$title" \
|
||||
"$slug"
|
||||
done
|
||||
|
||||
latest_version="$(grep -oE '"[0-9][^"]*"' "$REPO_ROOT/website/versions.json" 2>/dev/null | head -1 | tr -d '"' || true)"
|
||||
if [[ -n "$latest_version" && -d "$REPO_ROOT/website/versioned_docs/version-$latest_version" ]]; then
|
||||
for spec in "${doc_specs[@]}"; do
|
||||
IFS='|' read -r source target id title slug <<<"$spec"
|
||||
versioned_target="${target#website/docs/}"
|
||||
write_doc \
|
||||
"$REPO_ROOT/$source" \
|
||||
"$REPO_ROOT/website/versioned_docs/version-$latest_version/$versioned_target" \
|
||||
"$id" \
|
||||
"$title" \
|
||||
"$slug"
|
||||
done
|
||||
|
||||
sidebar="$REPO_ROOT/website/versioned_sidebars/version-$latest_version-sidebars.json"
|
||||
if [[ -f "$sidebar" ]]; then
|
||||
node - "$sidebar" <<'JS'
|
||||
const fs = require('fs');
|
||||
|
||||
const sidebarPath = process.argv[2];
|
||||
const data = JSON.parse(fs.readFileSync(sidebarPath, 'utf8'));
|
||||
const items = data.docsSidebar;
|
||||
|
||||
function category(label) {
|
||||
return items.find(item => item && typeof item === 'object' && item.label === label);
|
||||
}
|
||||
|
||||
function insertAfter(list, after, id) {
|
||||
if (list.includes(id)) return;
|
||||
const index = list.indexOf(after);
|
||||
list.splice(index === -1 ? list.length : index + 1, 0, id);
|
||||
}
|
||||
|
||||
insertAfter(category('Core Concepts').items, 'core-concepts/hash-ids', 'core-concepts/sync-concepts');
|
||||
insertAfter(category('Core Concepts').items, 'core-concepts/sync-concepts', 'core-concepts/labels');
|
||||
insertAfter(category('Core Concepts').items, 'core-concepts/labels', 'core-concepts/metadata');
|
||||
insertAfter(category('Recovery').items, 'recovery/sync-failures', 'recovery/uninstalling');
|
||||
insertAfter(category('Reference').items, 'reference/troubleshooting', 'reference/antivirus');
|
||||
|
||||
if (!items.includes('community-tools')) {
|
||||
const referenceIndex = items.findIndex(
|
||||
item => item && typeof item === 'object' && item.label === 'Reference'
|
||||
);
|
||||
const insertAt = referenceIndex === -1 ? items.length : referenceIndex;
|
||||
items.splice(insertAt, 0, 'community-tools');
|
||||
}
|
||||
|
||||
fs.writeFileSync(sidebarPath, `${JSON.stringify(data, null, 2)}\n`);
|
||||
JS
|
||||
fi
|
||||
fi
|
||||
391
test/docsync/docsync_test.go
Normal file
391
test/docsync/docsync_test.go
Normal file
|
|
@ -0,0 +1,391 @@
|
|||
// Package docsync keeps the Mintlify site under docs/ and its navigation in
|
||||
// docs/docs.json in exact correspondence, and keeps local markdown links
|
||||
// resolving across the documentation trees.
|
||||
//
|
||||
// Modeled on the Gas City docsync guard: nav entries must point at real
|
||||
// files, every published page must be in the nav (no orphans), and links are
|
||||
// checked with the convention of the tree they live in — docs/ links are
|
||||
// root-relative and extensionless (Mintlify routes), while engdocs/ and root
|
||||
// markdown are GitHub-viewed and need exact file paths.
|
||||
package docsync
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"runtime"
|
||||
"sort"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func repoRoot() string {
|
||||
_, filename, _, _ := runtime.Caller(0)
|
||||
return filepath.Join(filepath.Dir(filename), "..", "..")
|
||||
}
|
||||
|
||||
var markdownLinkRE = regexp.MustCompile(`\[[^][]*\]\(([^)]+)\)`)
|
||||
|
||||
// docsPublishExemptions lists markdown files under docs/ that are allowed to
|
||||
// exist without a docs.json navigation entry. Keep this list tiny: a file
|
||||
// belongs here only if it must stay at a stable GitHub path (released bd
|
||||
// binaries print it, or old deep links target it) or is generated for GitHub
|
||||
// consumption. Engineering docs belong in engdocs/, not here.
|
||||
var docsPublishExemptions = map[string]bool{
|
||||
"CLI_REFERENCE.md": true, // generated single-file reference (bd help --all)
|
||||
"QUICKSTART.md": true, // pointer stub; kept for old deep links
|
||||
"DOLT-BACKEND.md": true, // pointer stub; kept for old deep links
|
||||
"DOLT.md": true, // pointer stub; bd doctor output references it
|
||||
"STORAGE-BACKENDS.md": true, // pointer stub; bd init --backend help references it
|
||||
"PLUGIN.md": true, // pointer stub; bd doctor output references it
|
||||
"RECOVERY.md": true, // pointer stub; bd dolt output references its runbook anchors
|
||||
"JSON_SCHEMA.md": true, // pointer stub; bd schema-migration output references it
|
||||
}
|
||||
|
||||
// rootDocFiles are the curated root-level markdown files whose local links
|
||||
// are checked GitHub-style. CHANGELOG.md is deliberately absent: its
|
||||
// historical entries reference files that no longer exist.
|
||||
var rootDocFiles = []string{
|
||||
"README.md",
|
||||
"AGENTS.md",
|
||||
"AGENT_INSTRUCTIONS.md",
|
||||
"CONTRIBUTING.md",
|
||||
"CLAUDE.md",
|
||||
"RELEASING.md",
|
||||
"PR_MAINTAINER_GUIDELINES.md",
|
||||
}
|
||||
|
||||
func collectMintPages(v any, out *[]string) {
|
||||
switch x := v.(type) {
|
||||
case map[string]any:
|
||||
for k, child := range x {
|
||||
if k == "pages" {
|
||||
if arr, ok := child.([]any); ok {
|
||||
for _, item := range arr {
|
||||
if s, ok := item.(string); ok {
|
||||
*out = append(*out, s)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
collectMintPages(child, out)
|
||||
}
|
||||
case []any:
|
||||
for _, child := range x {
|
||||
collectMintPages(child, out)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func mintNavPages(t *testing.T) []string {
|
||||
t.Helper()
|
||||
data, err := os.ReadFile(filepath.Join(repoRoot(), "docs", "docs.json"))
|
||||
if err != nil {
|
||||
t.Fatalf("reading docs.json: %v", err)
|
||||
}
|
||||
var decoded map[string]any
|
||||
if err := json.Unmarshal(data, &decoded); err != nil {
|
||||
t.Fatalf("parsing docs.json: %v", err)
|
||||
}
|
||||
var pages []string
|
||||
collectMintPages(decoded, &pages)
|
||||
sort.Strings(pages)
|
||||
return pages
|
||||
}
|
||||
|
||||
func collectMarkdownFiles(root string) ([]string, error) {
|
||||
var files []string
|
||||
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if d.IsDir() {
|
||||
if name := d.Name(); path != root && (strings.HasPrefix(name, ".") || name == "node_modules") {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if ext := filepath.Ext(path); ext == ".md" || ext == ".mdx" {
|
||||
files = append(files, path)
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
sort.Strings(files)
|
||||
return files, nil
|
||||
}
|
||||
|
||||
func extractMarkdownLinks(content string) []string {
|
||||
matches := markdownLinkRE.FindAllStringSubmatchIndex(content, -1)
|
||||
var links []string
|
||||
for _, m := range matches {
|
||||
start := m[0]
|
||||
if start > 0 && content[start-1] == '!' {
|
||||
continue // image
|
||||
}
|
||||
target := strings.TrimSpace(content[m[2]:m[3]])
|
||||
target = strings.Trim(target, "<>")
|
||||
if target == "" {
|
||||
continue
|
||||
}
|
||||
if idx := strings.Index(target, ` "`); idx >= 0 {
|
||||
target = target[:idx]
|
||||
}
|
||||
links = append(links, target)
|
||||
}
|
||||
return links
|
||||
}
|
||||
|
||||
// stripCodeFences removes fenced code blocks so links inside examples are
|
||||
// not checked.
|
||||
func stripCodeFences(content string) string {
|
||||
lines := strings.Split(content, "\n")
|
||||
var out []string
|
||||
inFence := false
|
||||
for _, line := range lines {
|
||||
if strings.HasPrefix(strings.TrimSpace(line), "```") {
|
||||
inFence = !inFence
|
||||
continue
|
||||
}
|
||||
if !inFence {
|
||||
out = append(out, line)
|
||||
}
|
||||
}
|
||||
return strings.Join(out, "\n")
|
||||
}
|
||||
|
||||
func isExternalLink(target string) bool {
|
||||
switch {
|
||||
case strings.HasPrefix(target, "http://"),
|
||||
strings.HasPrefix(target, "https://"),
|
||||
strings.HasPrefix(target, "mailto:"),
|
||||
strings.HasPrefix(target, "tel:"),
|
||||
strings.HasPrefix(target, "#"):
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
func hasMdSuffix(target string) bool {
|
||||
path := target
|
||||
if idx := strings.IndexAny(path, "#?"); idx >= 0 {
|
||||
path = path[:idx]
|
||||
}
|
||||
ext := filepath.Ext(path)
|
||||
return ext == ".md" || ext == ".mdx"
|
||||
}
|
||||
|
||||
// routeExists reports whether a root-relative extensionless Mintlify route
|
||||
// (e.g. /getting-started/quickstart) resolves to a page under docs/.
|
||||
func routeExists(docsRoot, route string) bool {
|
||||
rel := filepath.FromSlash(strings.TrimPrefix(route, "/"))
|
||||
if rel == "" {
|
||||
rel = "index"
|
||||
}
|
||||
for _, try := range []string{
|
||||
filepath.Join(docsRoot, rel+".md"),
|
||||
filepath.Join(docsRoot, rel+".mdx"),
|
||||
filepath.Join(docsRoot, rel, "index.md"),
|
||||
filepath.Join(docsRoot, rel, "index.mdx"),
|
||||
filepath.Join(docsRoot, rel), // static assets (images)
|
||||
} {
|
||||
if info, err := os.Stat(try); err == nil && !info.IsDir() {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// TestMintNavigationPagesExist: every docs.json navigation entry points at a
|
||||
// real page under docs/.
|
||||
func TestMintNavigationPagesExist(t *testing.T) {
|
||||
root := repoRoot()
|
||||
var missing []string
|
||||
for _, page := range mintNavPages(t) {
|
||||
path := filepath.Join(root, "docs", filepath.FromSlash(page))
|
||||
if filepath.Ext(path) == "" {
|
||||
path += ".md"
|
||||
}
|
||||
if _, err := os.Stat(path); err != nil {
|
||||
mdx := strings.TrimSuffix(path, ".md") + ".mdx"
|
||||
if _, err2 := os.Stat(mdx); err2 != nil {
|
||||
missing = append(missing, page)
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(missing) > 0 {
|
||||
t.Errorf("docs.json references missing pages:")
|
||||
for _, page := range missing {
|
||||
t.Errorf(" %s", page)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestEveryDocsPageIsPublished: docs/ holds only published pages — every
|
||||
// markdown file must appear in docs.json navigation (or the tiny stub
|
||||
// allowlist). Engineering docs belong in engdocs/.
|
||||
func TestEveryDocsPageIsPublished(t *testing.T) {
|
||||
root := repoRoot()
|
||||
docsRoot := filepath.Join(root, "docs")
|
||||
|
||||
navPages := make(map[string]bool)
|
||||
for _, p := range mintNavPages(t) {
|
||||
navPages[strings.TrimSuffix(filepath.ToSlash(p), filepath.Ext(p))] = true
|
||||
}
|
||||
|
||||
files, err := collectMarkdownFiles(docsRoot)
|
||||
if err != nil {
|
||||
t.Fatalf("collecting docs markdown: %v", err)
|
||||
}
|
||||
|
||||
var orphans []string
|
||||
for _, path := range files {
|
||||
rel, err := filepath.Rel(docsRoot, path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
rel = filepath.ToSlash(rel)
|
||||
if docsPublishExemptions[rel] {
|
||||
continue
|
||||
}
|
||||
pageForm := strings.TrimSuffix(rel, filepath.Ext(rel))
|
||||
if !navPages[pageForm] {
|
||||
orphans = append(orphans, rel)
|
||||
}
|
||||
}
|
||||
|
||||
if len(orphans) > 0 {
|
||||
t.Errorf("docs/ markdown files not referenced in docs.json navigation.\n" +
|
||||
"docs/ publishes via Mintlify, so every page must be in the nav.\n" +
|
||||
"Add the file to docs/docs.json navigation (published page) or move it\n" +
|
||||
"under engdocs/ (engineering doc):")
|
||||
for _, o := range orphans {
|
||||
t.Errorf(" docs/%s", o)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestDocsSiteLinks: published docs/ pages use Mintlify link conventions —
|
||||
// internal links are root-relative and extensionless, and every route
|
||||
// resolves. Pointer stubs (GitHub-viewed) use exact relative paths instead.
|
||||
func TestDocsSiteLinks(t *testing.T) {
|
||||
root := repoRoot()
|
||||
docsRoot := filepath.Join(root, "docs")
|
||||
|
||||
files, err := collectMarkdownFiles(docsRoot)
|
||||
if err != nil {
|
||||
t.Fatalf("collecting docs markdown: %v", err)
|
||||
}
|
||||
|
||||
var broken []string
|
||||
for _, path := range files {
|
||||
rel, _ := filepath.Rel(docsRoot, path)
|
||||
rel = filepath.ToSlash(rel)
|
||||
isStub := docsPublishExemptions[rel]
|
||||
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("reading %s: %v", path, err)
|
||||
}
|
||||
for _, target := range extractMarkdownLinks(stripCodeFences(string(data))) {
|
||||
if isExternalLink(target) {
|
||||
continue
|
||||
}
|
||||
if isStub {
|
||||
// GitHub-viewed pointer stub: relative path must exist.
|
||||
resolved := target
|
||||
if idx := strings.IndexAny(resolved, "#?"); idx >= 0 {
|
||||
resolved = resolved[:idx]
|
||||
}
|
||||
if resolved == "" {
|
||||
continue
|
||||
}
|
||||
abs := filepath.Clean(filepath.Join(filepath.Dir(path), filepath.FromSlash(resolved)))
|
||||
if _, err := os.Stat(abs); err != nil {
|
||||
broken = append(broken, "docs/"+rel+" -> "+target)
|
||||
}
|
||||
continue
|
||||
}
|
||||
if hasMdSuffix(target) {
|
||||
broken = append(broken, "docs/"+rel+" -> "+target+" (.md suffix breaks Mintlify routes; link extensionless)")
|
||||
continue
|
||||
}
|
||||
if !strings.HasPrefix(target, "/") {
|
||||
broken = append(broken, "docs/"+rel+" -> "+target+" (published pages use root-relative links)")
|
||||
continue
|
||||
}
|
||||
route := target
|
||||
if idx := strings.IndexAny(route, "#?"); idx >= 0 {
|
||||
route = route[:idx]
|
||||
}
|
||||
if !routeExists(docsRoot, route) {
|
||||
broken = append(broken, "docs/"+rel+" -> "+target)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if len(broken) > 0 {
|
||||
sort.Strings(broken)
|
||||
t.Errorf("broken or misconvention links in docs/ (%d):", len(broken))
|
||||
for _, b := range broken {
|
||||
t.Errorf(" %s", b)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestEngdocsAndRootMarkdownLinks: engdocs/ and curated root markdown are
|
||||
// GitHub-viewed, so local links must be exact file paths.
|
||||
func TestEngdocsAndRootMarkdownLinks(t *testing.T) {
|
||||
root := repoRoot()
|
||||
|
||||
var files []string
|
||||
engdocs, err := collectMarkdownFiles(filepath.Join(root, "engdocs"))
|
||||
if err != nil {
|
||||
t.Fatalf("collecting engdocs markdown: %v", err)
|
||||
}
|
||||
files = append(files, engdocs...)
|
||||
for _, name := range rootDocFiles {
|
||||
path := filepath.Join(root, name)
|
||||
if _, err := os.Stat(path); err == nil {
|
||||
files = append(files, path)
|
||||
}
|
||||
}
|
||||
|
||||
var broken []string
|
||||
for _, path := range files {
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("reading %s: %v", path, err)
|
||||
}
|
||||
for _, target := range extractMarkdownLinks(stripCodeFences(string(data))) {
|
||||
if isExternalLink(target) {
|
||||
continue
|
||||
}
|
||||
resolved := target
|
||||
if idx := strings.IndexAny(resolved, "#?"); idx >= 0 {
|
||||
resolved = resolved[:idx]
|
||||
}
|
||||
if resolved == "" {
|
||||
continue
|
||||
}
|
||||
abs := filepath.Clean(filepath.Join(filepath.Dir(path), filepath.FromSlash(resolved)))
|
||||
if _, err := os.Stat(abs); err != nil {
|
||||
relPath, _ := filepath.Rel(root, path)
|
||||
broken = append(broken, filepath.ToSlash(relPath)+" -> "+target)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if len(broken) > 0 {
|
||||
sort.Strings(broken)
|
||||
t.Errorf("broken local markdown links (%d) — engdocs/ and root files are GitHub-viewed and need exact paths:", len(broken))
|
||||
for _, b := range broken {
|
||||
t.Errorf(" %s", b)
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue