Skip to content

docs: fix broken site images + in-body links + Slack app-install wording (#90)#314

Open
isadeks wants to merge 8 commits into
mainfrom
docs/90-slack-setup-images
Open

docs: fix broken site images + in-body links + Slack app-install wording (#90)#314
isadeks wants to merge 8 commits into
mainfrom
docs/90-slack-setup-images

Conversation

@isadeks

@isadeks isadeks commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Closes #90.

Problem

#90 reported the Slack setup screenshots 404 on the published docs site. Investigating surfaced two related docs-site issues:

  1. Missing images (the reported bug). The sync script rewrites ../imgs/foo.png/<base>/imgs/foo.png (served from docs/public/), but it never copied docs/imgs/ into docs/public/imgs/. The two pre-existing site images had been hand-copied; the four Slack screenshots were added to docs/imgs/ only, so they 404'd.
  2. Broken in-body design-doc links, site-wide. rewriteDocsLinkTarget emitted bare root-relative routes like /architecture/orchestrator with no base prefix. The site is served under base: /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's ARCHITECTURE.md / REPO_ONBOARDING.md links 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

  • copyAssetDir step in sync-starlight.mjs mirrors source imgs/ into public/imgs/, so every committed image is published (and future images won't regress). The four Slack PNGs are committed.
  • Base-prefix every rewritten in-body link with 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).
  • Reword the Slack app-install prerequisite.

Verification

Verified against a local astro preview (serves the exact dist/ output that ships to GitHub Pages, base path included):

  • All four Slack images return HTTP 200 at /sample-autonomous-cloud-coding-agents/imgs/... and render inline on the Slack guide.
  • Orchestrator in-body design-doc links now carry the base prefix; target pages (repo-onboarding, architecture) return 200.
  • yarn build → 62 pages, clean.

@isadeks isadeks requested a review from a team as a code owner June 10, 2026 22:45
…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.
@isadeks isadeks force-pushed the docs/90-slack-setup-images branch from 858dd22 to 9b5c01a Compare June 10, 2026 23:01
@isadeks isadeks requested a review from a team as a code owner June 22, 2026 18:51
bgagent added 2 commits June 22, 2026 15:15
…-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
ayushtr-aws previously approved these changes Jun 22, 2026

@ayushtr-aws ayushtr-aws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@isadeks

isadeks commented Jun 22, 2026

Copy link
Copy Markdown
Contributor Author

@ayushtr-aws thanks for the review! Addressed your nit in 041392e: removed the unreachable rewritten.startsWith('#') guard and rewrote the comment to explain why the prefix always applies (every non-undefined return from rewriteDocsLinkTarget is a /… route; bare #… anchors and external links return undefined and keep their original text). Verified the sync output is byte-identical — pure dead-code removal, no behavioral change. Mind re-approving? The new commit dismissed your approval.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: slack setup images

3 participants