docs: fix broken site images + in-body links + Slack app-install wording (#90)#314
docs: fix broken site images + in-body links + Slack app-install wording (#90)#314isadeks wants to merge 8 commits into
Conversation
…ing (#90) Three docs-site fixes: 1. Missing Slack setup images (the #90 report). The sync script rewrites `../imgs/foo.png` to an absolute `/<base>/imgs/foo.png` URL served from `docs/public/`, but never copied `docs/imgs/` → `docs/public/imgs/` — so the four Slack screenshots 404'd on the published site. Add a `copyAssetDir` step that mirrors source `imgs/` and `diagrams/` into `public/`, and commit the copied assets. Prevents recurrence for any future image. 2. Broken in-body design-doc links site-wide. `rewriteDocsLinkTarget` emitted bare root-relative routes (`/architecture/foo`) with no base prefix, so they resolved to the domain root and 404'd under the project base path. Starlight prefixes its own nav links automatically but not our rewritten markdown-body links. Prepend `docsBase` to every rewritten target (same prefix the image rewrite already uses). Re-synced all mirrors — the large diff is purely the base-path prefix on existing links. 3. Reword the Slack prerequisite away from "use a personal free workspace if your corporate Slack restricts app installs" — we don't want to suggest bypassing org controls. Now points users to request admin approval through their Slack administrator.
858dd22 to
9b5c01a
Compare
…-images # Conflicts: # docs/src/content/docs/architecture/Security.md # docs/src/content/docs/roadmap/Roadmap.md # docs/src/content/docs/using/Authentication.md # docs/src/content/docs/using/Overview.md
…-images # Conflicts: # docs/src/content/docs/architecture/Repo-onboarding.md # docs/src/content/docs/developer-guide/Contributing.md # docs/src/content/docs/developer-guide/Installation.md # docs/src/content/docs/developer-guide/Repository-preparation.md # docs/src/content/docs/getting-started/Deployment-guide.md # docs/src/content/docs/getting-started/Quick-start.mdx
ayushtr-aws
left a comment
There was a problem hiding this comment.
Verified locally. Minor nit: (dead startsWith('#') guard)
I traced every return path of rewriteDocsLinkTarget():
- all undefined, or
- a route from developerGuideAnchorRoutes / userGuideAnchorRoutes (start with /), or
- explicitGuideRoutes[stem] + anchorSuffix (starts with /), or
- /architecture/${slug}${anchorSuffix} (starts with /).
No non-undefined return can ever start with # — anchors are always appended as a suffix to a /… path. So rewritten.startsWith('#') ? rewritten : … is genuinely unreachable, and the comment ("Anchors #… stay untouched") is slightly misleading since a bare anchor returns undefined earlier. This one stands as written — harmless dead defensive code.
|
@ayushtr-aws thanks for the review! Addressed your nit in 041392e: removed the unreachable |
Closes #90.
Problem
#90 reported the Slack setup screenshots 404 on the published docs site. Investigating surfaced two related docs-site issues:
../imgs/foo.png→/<base>/imgs/foo.png(served fromdocs/public/), but it never copieddocs/imgs/intodocs/public/imgs/. The two pre-existing site images had been hand-copied; the four Slack screenshots were added todocs/imgs/only, so they 404'd.rewriteDocsLinkTargetemitted bare root-relative routes like/architecture/orchestratorwith no base prefix. The site is served underbase: /sample-autonomous-cloud-coding-agents, so those links resolved to the domain root and 404'd. (Starlight prefixes its own nav links automatically; our rewritten markdown-body links weren't.) This is what made the blueprint paragraph'sARCHITECTURE.md/REPO_ONBOARDING.mdlinks dead.Also reworded the Slack app-install prerequisite, which suggested using a personal workspace to get around corporate app-install restrictions — now points users at their Slack admin instead.
Fix
copyAssetDirstep insync-starlight.mjsmirrors sourceimgs/intopublic/imgs/, so every committed image is published (and future images won't regress). The four Slack PNGs are committed.docsBase— the same prefix the image rewrite already applies. Re-synced all mirrors; the bulk of the diff is purely the base-path prefix added to existing links (verified: no content changes).Verification
Verified against a local
astro preview(serves the exactdist/output that ships to GitHub Pages, base path included):/sample-autonomous-cloud-coding-agents/imgs/...and render inline on the Slack guide.repo-onboarding,architecture) return 200.yarn build→ 62 pages, clean.