Docs examples show and copy code that only exists for the preview

Open
#1,502 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
nuxt, typescript

Research direction

Start with apps/docs/DOCS_STANDARD.md, apps/docs/modules/component-examples.ts, and the ::component-example implementation to understand how example files feed the preview, code view, copy button, and markdown exports. Review the listed example and block files, then choose and implement a preview separation approach. Done means preview-only setup stays out of copied code, placeholders are presented as comments, and the copy button matches the code view.

Written by the indexing model from the issue text.

Description

Problem

Every example in the docs is a Vue file under apps/docs/app/components/content/examples/ (blocks: apps/docs/app/components/content/blocks/). The docs use that file as it is:

  • as the code below the preview, and for its copy button
  • in the markdown of the page: "Copy page", "View as Markdown", llms-full.txt and the get-page tool of the docs MCP server

Many of these files also hold code that only makes the preview fit into the docs page. Developers and AI assistants copy it into their apps:

  • Placeholders: <placeholder-slot> stands in for slot content, 30 times in 13 example and block files. It only exists in the docs app, so copied code can't resolve it: Vue warns, and nothing shows.
  • Props that change behavior: the App example sets :breakpoint="0", which turns off the mobile layout, and --mt-app-height: 480px, which fixes the height of the shell. The App Header example needs the same: its 1024px breakpoint compares the header's own width, and the preview is narrower than that on most screens.
  • Frames: wrappers and inline styles that size or decorate the preview, such as heights (Page, App Sidebar, Nav), widths (User Menu), backgrounds, dashed borders and padding (Layout, Container) and resize: horizontal handles (Breadcrumb, Page, Layout).
  • Layout of several variants: display: flex or grid wrappers that only line up variants next to each other (Status Dot, Divider, Breadcrumb sizes, Theme Select).
  • Stand-ins: the Nav examples define a DemoLink component in place of router-link, so a click doesn't leave the docs page.

In total, 39 example and block files have inline styles, in 52 places. Most placeholders, frames and stand-ins come with the docs of the app shell components (App, Page, Layout, Container, Nav, App Sidebar, App Header). Some inline styles are real usage and stay, such as the sized, positioned container of Loader, the trigger width in the "match trigger width" example of Action Menu, and the 15rem width that the best practices of Nav recommend.

::component-example already has a #code slot for a hand-written code block. The code view and the markdown export use it, but the copy button still copies the example file.

Proposal

Rule for apps/docs/DOCS_STANDARD.md: the example file is the code that readers copy. Anything that only makes the preview fit goes on ::component-example in the page.

Option 1: preview settings on ::component-example (recommended)
  • A new props option, passed to the example and through Vue's attribute fallthrough on to its root. It takes docs-only props and sizes of the documented component:

    ::component-example{name="app-basic-example" fullWidth inset :props='{"breakpoint": 0, "style": "--mt-app-height: 480px"}'}
    ::
    
  • The existing class option takes the frame of the preview: a background, a padding, a column layout or a resize handle.

  • Examples that show several variants get a template with several roots, which the preview container lines up (flex flex-wrap gap-4).

Nuxt UI, whose example module ours is adapted from, does it this way (props and class on its ComponentExample), and ::block-preview already takes its height from the page. It only reaches the root of the example, not elements inside its slots.

Option 2: mark preview-only code in the file

The docs remove marked code from the shown code: a frame element with a marker attribute, such as data-docs-frame, is unwrapped, and <!-- #region preview --> blocks are dropped (VitePress uses #region markers to import parts of a file). Everything stays in one file, but it needs a template transform, and a single attribute such as :breakpoint="0" can't be marked inside a tag.

Option 3: write the shown code by hand

Every affected example gets a hand-written #code block. No new mechanism, but each example exists twice, and the two copies drift apart.

With any option
  • Copy button: copies what the code view shows, also a hand-written #code block.
  • Placeholders: the code shows <placeholder-slot name="x" /> as <!-- x -->. One transform where the docs read the example files (apps/docs/modules/component-examples.ts) covers the code view, the copy button and the markdown export. The alternative is real content in place of the placeholders, which runs as copied but makes the examples longer and the slots harder to see.
  • Stand-ins: the preview keeps links from leaving the page with a click listener that calls preventDefault(), which router-link respects. The Nav examples can then use the default link component.
  • Width-dependent components (optional): App and App Header get a preview at desktop width, as Nuxt UI does with its iframe option, which renders an example in a 1024px wide frame. They then show their desktop layout with the default breakpoint and need no docs-only prop.
Dominant language
TypeScript
Stars
37
Forks
24
Avg merge
3d 7h
Merged PRs (30d)
24

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from shopware/meteor

All issues in shopware/meteor

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.