Skip to main content

​
Cross-Workspace Link Strategy: Relative vs. Absolute URLs

​
The Core Insight

When you have multiple doc sites across multiple repos, your link strategy determines whether they can deploy independently. Relative links create coupling; absolute HTTPS URLs create freedom. We learned this by separating GRACE docs from STRATT docs and managing links carefully.

​
The Two Strategies

​
❌ Bad: Local paths (coupling)

# stratt-hq/apps/meridian/src/content/docs/getting-started.md
[Protocol spec](/spec/grace/v1-0/)
Problems:
  • Breaks if grace-hq folder structure changes
  • Assumes grace-hq is deployed alongside MERIDIAN (coupled)
  • Can’t redirect to grace.devarno.cloud without breaking links
  • Becomes a tech debt trap: “we’d love to separate these but too many links”

​
✅ Good: Absolute HTTPS URLs (decoupling)

# stratt-hq/apps/meridian/src/content/docs/getting-started.md
[Protocol spec](https://grace.devarno.cloud/protocol/specification/)
Benefits:
  • Works regardless of grace-hq deployment location
  • Gracefully handles DNS/URL changes (update grace.devarno.cloud → new server)
  • Both sites deploy independently on their own schedules
  • Clear architectural boundaries (MERIDIAN doesn’t assume Grace’s topology)

​
Level 1: Intra-site (within same doc site)

Location: grace-hq docs or MERIDIAN docs, linking to pages in same site Strategy: Relative paths with / prefix 
# grace-hq/docs/assistant/heartbeat.md
[Overview](/assistant/overview/)
[Protocol Spec](/protocol/specification/)
Why: Short, fast, works offline, familiar to readers. Astro/Starlight compile these automatically.

​
Level 2: Inter-site (GRACE ↔ STRATT)

Location: grace-hq docs linking to stratt.dev, or vice versa Strategy: Absolute HTTPS URLs 
# grace-hq/docs/protocol/specification.md
[Units implementation](https://stratt.dev/units/overview/)

# stratt-hq/apps/meridian/src/content/docs/getting-started.md
[GRACE Protocol](https://grace.devarno.cloud/protocol/overview/)
Why: Decouples deployment. Either site can change URLs without breaking the other.

​
Level 3: Cross-workspace discovery (atlas learnings → grace docs)

Location: atlas learnings linking to grace-hq docs Strategy: Absolute HTTPS URLs 
# atlas/learnings/2026-04-07-grace-docs-separation-pattern.md
See the [GRACE Protocol](https://grace.devarno.cloud/protocol/overview/) for specs.
Why: learnings/ is business-facing (less technical); readers may share links externally. Absolute URLs remain valid when shared.

​
The Real Problem This Solves

Imagine this scenario (pre-migration, problematic): 
1. Developer writes: [Grace spec](/spec/grace/v1-0/)
2. Site deploys to stratt.dev/spec/grace/v1-0/
3. Six months later, someone decides to move GRACE docs to grace.devarno.cloud
4. Now 47 links across MERIDIAN break
5. Panic: "We're too coupled to change the URL."
6. Result: Docs stay forever at stratt.dev, preventing independent Grace deployment
With absolute URLs: 
1. Developer writes: [Grace spec](https://grace.devarno.cloud/protocol/specification/)
2. grace.devarno.cloud domain points to Netlify
3. Six months later, you want to move to Railway
4. Update DNS → grace.devarno.cloud now points to Railway
5. Zero link changes needed
6. Bonus: MERIDIAN doesn't need to rebuild

​
Implementation Pattern

grep -r '\[.*\](/' grace-hq/docs/  # relative links
grep -r '\[.*)https://' grace-hq/docs/  # absolute links

​
Step 2: Categorize by type

  • Intra-site (grace-hq → grace-hq) = relative / prefix ✅
  • Inter-site (grace-hq → stratt.dev) = absolute https://stratt.dev ✅
  • Inter-site (meridian → grace.devarno.cloud) = absolute https://grace.devarno.cloud ✅
  • Inter-site (anything → external source) = absolute HTTPS ✅
# Sample 20 random external links and verify 200 OK
curl -s -I https://grace.devarno.cloud/protocol/overview/ | grep "200"
curl -s -I https://stratt.dev/cli/overview/ | grep "200"
If you move a domain (e.g., grace.devarno.cloud → grace.ai), update all docs that reference it: 
find . -type f -name "*.md" \
  -exec sed -i 's|https://grace.devarno.cloud|https://grace.ai|g' {} \;
But this is optional because readers use the DNS-based URL, not the hardcoded old URL.

​
Edge Cases

​
Case 1: Linking within a deep nested structure

# grace-hq/docs/architecture/primer.md
[Back to protocol](/protocol/overview/)  ← relative, works
[Sibling: gap analysis](/architecture/gap-analysis/)  ← relative, works

# Intra-site with anchor
[SPEC-02 Fingerprinting](/protocol/specification/#spec-02-fingerprinting)

# Cross-site with anchor (absolute)
[SPEC-02 in Grace docs](https://grace.devarno.cloud/protocol/specification/#spec-02-fingerprinting)

​
Case 3: External image hosting

# If images live on CDN (e.g., S3)
![Architecture diagram](https://cdn.example.com/grace-architecture.svg)

# If images live in repo
![Architecture diagram](/images/grace-architecture.svg)  ← relative

​
Maintenance Checklist

Monthly:
  • Run bun run build on both grace-hq and MERIDIAN
  • Sample 10 cross-site links: curl -I https://grace.devarno.cloud/...
  • Check sidebar structure matches docs folder structure
Quarterly:
  • Grep for stub links (TODO, STUB, [link to be filled in])
  • Audit for protocol links in MERIDIAN (should all be absolute to grace.devarno.cloud)
Before deploying to new domain:
  • Update DNS record
  • Test 20 random absolute URLs resolve to new domain
  • No code changes needed (links use domain, not hardcoded IPs)

​
Why Absolute URLs Are Non-Negotiable

  1. Future-proofs migrations: Move domains without touching 1,000 docs
  2. Enables monitoring: Can track which sites link to you (HTTP referrer headers)
  3. Respects repo boundaries: MERIDIAN doesn’t need to know grace-hq’s structure
  4. Facilitates mirrors: If grace.devarno.cloud goes down, can stand up a mirror without rewriting links
  5. Simplifies API generation: If you auto-generate docs from an API, absolute URLs work across any deployment target

​
Applicable Beyond GRACE

Use this pattern when:
  • You have >1 documentation site
  • Sites are owned by different teams or orgs
  • You want independent deployment schedules
  • You plan to migrate domains or hosting providers
  • You want to avoid “tech debt coupling” where moving docs becomes impossible
Related: GRACE Documentation Separation (why we needed separate sites), Taskset-Gated Documentation Workflow (how we managed the migration process).