Skip to content

Comments

docs(admin-extensions): migrate static pages to MDX and update build process#3943

Open
MitchLillie wants to merge 1 commit into2026-04-rcfrom
cx-apply-slack-retry-rc
Open

docs(admin-extensions): migrate static pages to MDX and update build process#3943
MitchLillie wants to merge 1 commit into2026-04-rcfrom
cx-apply-slack-retry-rc

Conversation

@MitchLillie
Copy link
Contributor

@MitchLillie MitchLillie commented Feb 20, 2026

Summary

  • Replaces legacy `doc.ts` static landing page files with MDX files copied from shopify-dev (source of truth)
  • Updates `build-docs.mjs` to copy MDX static pages to `areas/platforms/shopify-dev/content/api/admin-extensions/${version}/` during doc generation, replacing the now-broken `generate-docs --isLandingPage` pipeline

What changed

  • Deleted: `staticPages/admin-extensions.ext.doc.ts`, `targets-overview.ext.doc.ts`, `network-features.ext.doc.ts`
  • Added: `staticPages/index.mdx`, `staticPages/targets.mdx`, `staticPages/network-features.mdx` (copied from shopify-dev)
  • Updated: `build-docs.mjs` — removed the two broken static page generation commands, added MDX copy step to shopify-dev

Why

The `generate-docs --isLandingPage` pipeline no longer syncs pages to shopify.dev. Static pages are now individual MDX files in shopify-dev (per #10920). The package MDX files are the source of truth and get copied to shopify-dev on each docs generation run.

Testing

Requires a local monorepo checkout with both `ui-extensions` and `shopify-dev` co-located (i.e. `shopify-dev` is at `../../../shopify-dev` relative to `packages/ui-extensions/`).

  1. Check out this branch
  2. Run the docs generation script:
    yarn docs:admin
    # or for a specific version:
    yarn docs:admin 2026-04
  3. Verify the three MDX files were copied to shopify-dev:
    ls ../../../shopify-dev/areas/platforms/shopify-dev/content/api/admin-extensions/unstable/
    # Expected: index.mdx  network-features.mdx  targets.mdx
  4. Confirm the script completed without errors related to missing `.doc.ts` files or `generate-docs --isLandingPage`

Without a monorepo checkout: the script will print Not copying docs to shopify-dev because it was not found and exit cleanly — no errors expected.

🤖 Generated with Claude Code

…process

Replace static doc.ts landing page files with MDX files copied from
shopify-dev. Update build-docs.mjs to copy MDX static pages to the
correct shopify-dev path during doc generation instead of running the
now-broken generate-docs --isLandingPage pipeline.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mcvinci
Copy link
Contributor

mcvinci commented Feb 21, 2026

Hey @MitchLillie! I could be missing a ton of context (and apologies if I am!), but I think an easier route might be to have the MDX pages live only in shopify-dev versus copying over MDX files in ui-extensions to shopify-dev. Maybe we can just delete the static landing pages here altogether?

cc: @majd-shopify @johndcollett

@johndcollett
Copy link

The plan on shopify-dev side was to have the MDX files all live inside of Shopify-dev as we are not exporting the components that are being used in them. There is no guarantee that we won't change the API of those components and update all MDX files in our repo with the resulting change. If your files are outside of this then they won't get updated.

Also since this is not the plan for all repos you would be in a situation where your MDX files are not to be edited in our repo but everyone else's are which is not something we want.

For now I'd prefer to keep the source of truth for these files in MDX especially as things are in flux on our end. If this becomes a pain point for your team I'm happy to talk more about it to see what we can do to remedy that.

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.

3 participants