Docs examples show and copy code that only exists for the preview
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
- Domain
- developer-experience, documentation, frontend
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.txtand theget-pagetool 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: horizontalhandles (Breadcrumb, Page, Layout). - Layout of several variants:
display: flexorgridwrappers that only line up variants next to each other (Status Dot, Divider, Breadcrumb sizes, Theme Select). - Stand-ins: the Nav examples define a
DemoLinkcomponent in place ofrouter-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
propsoption, 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
classoption 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
#codeblock. - 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(), whichrouter-linkrespects. 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
iframeoption, 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
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from shopware/meteor
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
package: components
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
Maintainers usually reply within 1 day
-
area/accessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
package: components priority/low
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
vega/vega-webgpu#40 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
openwatersio/slackwater#550 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
bug size:small
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
fb55/htmlparser2#2579 ·
Maintainers usually reply within 1 day