Reusable lstk components#817
Open
remotesynth wants to merge 2 commits into
Open
Conversation
**Built:** - 12 shared components in [src/components/lstk/](src/components/lstk/) covering Installation, QuickStart, Authentication, Configuration, LifecycleCommands, SnapshotCommands, CommonCommands, GlobalOptionsAndOutput, EnvironmentAndLogging, ShellCompletions, FaqCommon, and TroubleshootingCommon. - Rewrote the [AWS](src/content/docs/aws/developer-tools/running-localstack/lstk.mdx) and [Azure](src/content/docs/azure/developer-tools/lstk.mdx) pages to import them, keeping only what's native to each emulator. - Added the new [Snowflake page](src/content/docs/snowflake/developer-tools/lstk.mdx) plus a "Developer Tools" sidebar section in [astro.config.mjs](astro.config.mjs). - [src/lib/lstk-toc.ts](src/lib/lstk-toc.ts) + a hook in [src/routeData.ts](src/routeData.ts) that stitches shared-component headings into the right-hand nav automatically — verified all three pages now show a complete, correctly-ordered TOC. - Added a scoped `exclude` to `starlight-links-validator` in `astro.config.mjs` for same-page hash links on these files, since that plugin checks each file in isolation and can't see the cross-file composition. **Bugs fixed along the way** (all things you flagged wanting checked): - Azure's page no longer shows AWS-only commands (`aws`, `terraform`, `cdk`, `sam`, `setup aws`, `reset`) or the AWS-only "save/restore state" FAQ item. - Azure regained the "Structured output"/"Exit codes" section it had silently drifted out of sync on. - Fixed a broken volume-mounts example (AWS page linked to Snowflake-specific docs). - Fixed a real broken link: the Prerequisites section linked to `#managing-your-license` on the AWS auth-token page, but that page's heading is actually "License assignment" — fixed to `#license-assignment`. - `MAIN_CONTAINER_NAME`'s default value was hardcoded as `localstack-aws` in shared docs; genericized to reflect the configured emulator type. **Verified:** rendered all three pages in-browser, confirmed content and TOC accuracy, confirmed AWS-only content correctly appears/disappears via the `emulator` prop, and ran a full `npm run build`.
- **AWS page**: `snapshot` content inlined natively (it's no longer shared with anything, so the component was folded back in and deleted) — kept full Cloud Pods/S3/local support, dropped the inaccurate "also works experimentally on Snowflake/Azure" note. - **Azure page**: removed `snapshot`/`reset` entirely, added a short note pointing to `--persist` as the only state-retention option, and fixed the Introduction paragraph, which previously claimed Cloud Pod support. - **Snowflake page**: replaced the shared component with a native `snapshot` section scoped to local files only — no `pod:` refs, no S3 remotes, no `list`/`remove`/`show` (all Cloud-Pod-only) — kept the "experimental" warning since that's specifically about local save/load, and fixed its Introduction paragraph too. - Annotated the global `--snapshot`/`--no-snapshot` flags as AWS-only in `GlobalOptionsAndOutput.mdx` for consistency.
remotesynth
requested review from
HarshCasper and
quetzalliwrites
as code owners
July 24, 2026 15:10
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is an attempt to create the various lstk pages out of reusable components that cover the shared content. We should decide whether this adds too much complexity to solve the reusability problem. The issue is that many sections of the lstk docs contain caveats that make them not entirely reusable. In addition, this requires more complex logic in our middleware due to the fact that TOC headings from imported components don't automatically render in the right sidebar. A concern is that this makes maintainability more complex rather than less because many pieces are not reused or contain logic for a specific emulator.
Here's a summary of changes:
Splits the
lstkCLI reference page — previously duplicated near-verbatim across AWS and Azure, and already drifted out of sync between the two — into a shared set of MDX components plus a thin per-emulator page. Also adds the missing Snowflakelstkpage.Shared components (
src/components/lstk/)New reusable
.mdxcomponents for content that's genuinely identical across emulators:Installation,QuickStart,Authentication,Configuration,LifecycleCommands(start/stop/restart/status/logs),CommonCommands(volume/login/logout/config/update/completion),GlobalOptionsAndOutput,EnvironmentAndLogging,ShellCompletions,FaqCommon,TroubleshootingCommon.LifecycleCommandstakes anemulatorprop to gate the two AWS-only bits (snapshot autoload onstart, resource listing onstatus).Each of the three pages now imports these and adds only what's genuinely specific to that emulator (its own Introduction/Prerequisites text, and commands like
aws/terraform/cdk/sam/setup aws/resetfor AWS,az/setup azurefor Azure).Pages
src/content/docs/aws/developer-tools/running-localstack/lstk.mdx) and Azure (src/content/docs/azure/developer-tools/lstk.mdx): rewritten to compose from the shared components.src/content/docs/snowflake/developer-tools/lstk.mdx): added, plus a new "Developer Tools" sidebar section inastro.config.mjs.Content accuracy fixes
aws,terraform,cdk,sam,setup aws,reset) it never actually had.lstk start --persist). Snowflake supportssnapshot save/loadwith local files only — no Cloud Pods, no S3 remotes, nolist/remove/show(all Cloud-Pod-only), flagged as experimental.#managing-your-license, which doesn't exist on the AWS auth-token page (it does on Azure/Snowflake's) — corrected to#license-assignment.MAIN_CONTAINER_NAMEcontainer-injected-variable row, previously hardcoded tolocalstack-awsregardless of emulator.--snapshot/--no-snapshotflags as AWS-only.Right-hand nav (TOC) fix
Starlight builds its TOC from each page's own compiled headings, so headings coming from an imported
.mdxcomponent were invisible to it. Addedsrc/lib/lstk-toc.ts+ a hook insrc/routeData.tsthat parses each lstk page's source (and the shared components it imports), extracts headings withgithub-slugger(matching Astro's own per-file slugging), and stitches them intostarlightRoute.toc.itemsin document order.Other
excludeto thestarlight-links-validatorconfig for same-page#hashlinks on the lstk page/component files, since that plugin validates each file in isolation and can't see the cross-file composition (the anchors themselves are real and verified via the TOC fix above).github-sluggeras an explicit dependency.Testing
Rendered all three pages in-browser; confirmed content, TOC accuracy/ordering, and AWS-only conditional content appear/disappear correctly per emulator. Ran a full
npm run build— passes except for ~27 pre-existing broken links in unrelated files (not touched by this change).