feat(docs): add theme, components, and astro config changes by janelletam · Pull Request #24 · botpress/docs-v2

janelletam · 2026-05-29T14:24:50Z

Summary

Add UI infrastructure for docs-v2, including:
- New Astro components (CodeGroup, LazyIframe, ResponseField)
- Scripts (code-copy, code-icons, step-anchors)
- Shared icon utility
Refactor global.css to use CSS variables using oklch values for colours and improve accessibility
Update astro.config.mjs, sidebar/layout components, and clean up duplicate/unused code from initial scaffold

Test plan

Verify code blocks render with copy button and language icon
Verify CodeGroup, ResponseField, and LazyIframe components render correctly
Check light/dark theme switching -> colors should use CSS variables consistently
Confirm breadcrumbs render correctly
Check sidebar and mobile sidebar navigation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

greptile-apps · 2026-05-29T14:29:43Z

Greptile Summary

This PR adds theme variables, a suite of new components (CodeGroup, LazyIframe, ResponseField, Step anchors), Shiki code transformers (filename, expandable, meta-highlight), astro-icon integration, and a global CSS overhaul with styles for code blocks, heading anchors, and step counters.

astro.config.mjs: Adds astro-icon, three Shiki transformers, prefetch-all config, and switches rehype-autolink-headings from wrap to prepend behavior with an inline SVG link icon.
src/scripts/: Three new client scripts (code-copy.ts, step-anchors.ts) and a shared icon constants module (code-icons.ts) extracted from inline script tags.
Components: Icon.astro now uses astro-icon with toLucideKebab normalization; ReactIcon.tsx provides a parallel React-side icon resolver; sidebar and mobile-sidebar nav icon rendering unified via ReactIcon.

Confidence Score: 4/5

Safe to merge with one fix: step-anchors.ts needs an idempotency guard to avoid duplicate click handlers on initial load.

All four initialization scripts listen to both DOMContentLoaded and astro:page-load, which both fire on initial load. Three have idempotency guards; step-anchors.ts does not, causing duplicate click handlers on every step anchor during the initial page visit. The rest of the PR is well-structured.

src/scripts/step-anchors.ts

Important Files Changed

Filename	Overview
src/scripts/step-anchors.ts	New script for step anchor click handling; duplicate event listener registration on initial load causes double-fired scroll and clipboard calls.
astro.config.mjs	Adds Shiki transformers (filename, expandable, meta-highlight), rehype-autolink-headings with prepend behavior, prefetch config, and astro-icon integration.
src/components/CodeGroup.astro	New component for tabbed code groups; correctly uses data-ready guard to prevent double-initialization across DOMContentLoaded and astro:page-load.
src/scripts/code-copy.ts	New script wrapping standalone code blocks with copy and expand buttons; guarded against double-init via .code-block-wrapper parent check.
src/components/LazyIframe.astro	New component for lazily loading iframes via IntersectionObserver; idempotency is safe since it checks iframe.src before observing.
src/lib/icon-utils.ts	New utility exporting toPascalCase, toLucideKebab, and slugify; logic is correct for all expected input forms.
src/styles/global.css	Large stylesheet expansion adding code block, code group, expandable, heading anchor, and step anchor styles.
src/components/Icon.astro	Switched from lucide-react to astro-icon with toLucideKebab normalization, enabling both PascalCase and kebab-case icon names.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Page Load] --> B[DOMContentLoaded]
    A --> C[astro:page-load]
    B --> D[initCopyButtons guarded]
    B --> E[initStepAnchors no guard]
    B --> F[initLazyIframes guarded]
    B --> G[initCodeGroups guarded]
    C --> D
    C --> E
    C --> F
    C --> G
    E -- double listeners on initial load --> H[Step Anchor Click]
    H --> I[scrollIntoView x2 and pushState x2]

_{Reviews (3): Last reviewed commit: "fix(docs): fix incorrect import" | Re-trigger Greptile}

janelletam · 2026-05-29T15:41:10Z

@greptileai

…c oklch values

…sability

janelletam · 2026-05-29T18:50:18Z

@greptileai

sea-grass · 2026-05-29T20:17:46Z

-          <div class="hidden items-start justify-between gap-4 lg:flex">
-            {breadcrumbs.length > 0 ? (
-              <Breadcrumb className="min-w-0 flex-1">
+          {breadcrumbs.length > 1 && (


suggestion: Let's keep the previous behaviour where we render only the top-level breadcrumb as well.

sea-grass · 2026-05-29T20:25:28Z

+import { toLucideKebab } from "@/lib/icon-utils";

 interface Props {
-  icon: keyof typeof icons;


suggestion: let's keep using lucide icons, this way we get intellisense/type errors if we try to use an icon that's misspelled or that doesn't exist.

sea-grass · 2026-05-29T20:35:45Z

+  ></iframe>
+</div>
+
+<script>


issue: LLMs have a tendency to create astro components with inline scripts. The problem is these scripts are present on the page as many times as the component is rendered. Instead, if we need JS to run on the client, we should make a React component and use an astro client:load or client:idle directive to create an island/hydrate it on the client.

If this is used in content, I might suggest this pattern:

// content/some-page.mdx <LazyIframe ... /> (astro component)

// components/LazyIframe.astro <LazyIframe ... client:load /> (react component)

This way, the content editor can still use the simple form and not have to worry about including the directive.

sea-grass · 2026-05-29T20:40:45Z

      siteLogo={siteConfig.logo}
      siteLogoDark={siteConfig.logoDark}
-      breadcrumbs={breadcrumbs}
+      breadcrumbs={[...(breadcrumbs ?? []), { label: title }]}


issue: It seems like not rendering the page itself in the breadcrumbs was an intentional design decision (see the comment in src/bach/breadcrumbs.ts buildBreadcrumbs), so let's keep this as-is.

sea-grass · 2026-05-29T20:41:50Z

 </BaseLayout>
+
+<script>
+  import '@/scripts/code-copy'


suggestion: Instead, let's make the code blocks an astro component that wraps a hydrated react component.

sea-grass · 2026-05-29T20:42:14Z

+
+<script>
+  import '@/scripts/code-copy'
+  import '@/scripts/step-anchors'


question: Is it possible to include the code for these as a hydrated react component rather than a separately included script?

sea-grass · 2026-05-29T20:58:11Z

+import { transformerMetaHighlight } from '@shikijs/transformers'
+
+/** @returns {import('shiki').ShikiTransformer} */
+function transformerFilename() {


suggestion: move these transformers into src/shiki/transformers/*

feat(docs): add theme, components, and astro config changes

aa574f5

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

greptile-apps Bot reviewed May 29, 2026

View reviewed changes

Comment thread src/styles/global.css Outdated

Comment thread src/components/CodeGroup.astro Outdated

Comment thread .claude/commands/docs-migrator.md

janelletam added 9 commits May 29, 2026 14:32

chore(docs): clean up duplicate/unused code

bb588f5

refactor(docs): improve accessibility + use variables instead of magi…

9a31bcb

…c oklch values

fix(docs): fix merge conflicts

3b5402b

refactor(docs): update icon casing naming in bash config

3a06bc8

chore(docs): clean up some unused code + update claude skill

f338c57

chore(docs): update to PascalCasing

d006f45

refactor(docs): fix bug with breadcrumbs and use variables for colours

34cf802

refactor(docs): fix trailing char, typo

5eb9d08

refactor(docs): move icon over to code-icons.ts script for better reu…

68902b5

…sability

janelletam force-pushed the janelle/docs-v2/visual-differences branch from 0865088 to 68902b5 Compare May 29, 2026 18:37

janelletam and others added 4 commits May 29, 2026 14:41

refactor(docs): change icon to use lucide-react

ac29532

chore(docs): remove unused import

2138caa

Merge branch 'master' into janelle/docs-v2/visual-differences

598079d

fix(docs): fix incorrect import

3fc10d9

sea-grass reviewed May 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): add theme, components, and astro config changes#24

feat(docs): add theme, components, and astro config changes#24
janelletam wants to merge 14 commits into
masterfrom
janelle/docs-v2/visual-differences

janelletam commented May 29, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented May 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janelletam commented May 29, 2026

Uh oh!

janelletam commented May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

sea-grass May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

janelletam commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

greptile-apps Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janelletam commented May 29, 2026

Uh oh!

janelletam commented May 29, 2026

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

sea-grass May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

janelletam commented May 29, 2026 •

edited

Loading

greptile-apps Bot commented May 29, 2026 •

edited

Loading