Components preview
I am creating a custom nuxt module with some basic components. I have @nuxt/content docs website with @nuxt/ui, and I want to easily write a component code in the docs inside and then have it displayed nicely with the code with proper highlighting and working component on the other side.
Nuxt ui docs have something similar, but it is very complex and I don't want to copy it, nuxt content docs have some too, but it is used only to showcase markdown rendering. Any ideas/suggestions how to do it?
8 Replies
Hi @Norbiros. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
To achieve a component preview in your Nuxt Content docs—where you can both display the component and its source code with proper highlighting—there are built-in solutions in the Nuxt ecosystem that are much simpler than the full Nuxt UI docs setup.
Use MDC Syntax with Nuxt Content
Nuxt Content supports MDC syntax, which allows you to embed Vue components directly in your Markdown files. You can place your component in the
/components/content directory and then use it in your Markdown like this:
This will render the component live in your docs. However, this does not automatically show the source code.
Displaying Code and Preview Side-by-Side
For a simple and effective solution, you can use the code-preview component from Nuxt UI Pro, which is designed for exactly this use case. It lets you wrap a code block and display both the rendered component and its code with syntax highlighting:
vue
<MyComponent prop="value" />
- The #default slot renders the live component.
- The code slot displays the code with highlighting.
This approach is used in Nuxt UI Pro docs and is much simpler than building a custom solution from scratch. You can customize the appearance via your app.config.ts if needed. Code highlighting is handled by Shiki, and you can configure themes in your nuxt.config.ts under content.build.markdown.highlightNuxt UI Typography, Nuxt Content Markdown Highlight.
Requirements
- Install and configure Nuxt UI Pro in your project.
- Place your components in the appropriate directory.
- Use MDC syntax in your Markdown files as shown above.
Summary
- Use MDC syntax to embed components.
- Use code-preview from Nuxt UI Pro to show both the live component and its code with highlighting.
- Configure code highlighting and appearance as needed.
This gives you a clean, maintainable, and Nuxt-native way to showcase your components in your documentation without copying complex setups.
If you need more advanced customization, you can override the code-preview or prose components by placing your own versions in components/content/Prose Components.
Let me know if you need a concrete example or further details!
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@770620808644919307> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai
I don't want to duplicate code in 2 places. I also want to show complex use cases with script setup where i define some props and then pass them to my component
Let me check the knowledge base for you again. One moment! :books:
----------------------
I'm sorry, but the knowledge sources do not provide a ready-made solution for displaying both the live preview and the source code of a complex component example (including
- You can embed components and show code, but not from a single source of truth without duplication, according to the current documentation and examples. - For complex use cases with
<script setup> logic and props) in Nuxt Content docs without duplicating code.
The typical approaches shown in the sources involve either:
- Embedding components directly in Markdown using MDC syntax, which renders the component but does not show the code automatically, nor does it support including <script setup> logic inline with the preview Nuxt Content Docs Studio Vue Components.
- Using a custom or third-party component (like code-preview in Nuxt UI Pro) where you still need to write the code twice: once for the live preview and once for the code block Nuxt UI Typography.
There is no documented way in the provided sources to write a single file (with both template and script) and have it both rendered and displayed as highlighted code in your docs, without duplication.
Summary:- You can embed components and show code, but not from a single source of truth without duplication, according to the current documentation and examples. - For complex use cases with
<script setup>, props, and logic, you would need to maintain both the example component and its code snippet separately in your docs.
If you need a more advanced, DRY solution, it would require a custom implementation, which is not covered in the official docs or examples provided in the knowledge sources.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@770620808644919307> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai maybe I can create a custom component, or maybe there are some other community made projectst that solve it
Let me check the knowledge base for you again. One moment! :books:
----------------------
Based on the provided knowledge sources, there is no official or community-maintained Nuxt Content or Nuxt UI component documented that allows you to write a single file (with both
- You can create a custom component, but it won't eliminate code duplication by default. - There are no documented community projects in the provided sources that solve this in a DRY way. - Any advanced solution would require custom development beyond what is described in the official docs. If you need more details on how to create a basic custom component for previews, let me know! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
<script setup> and template) and have it both rendered as a live preview and displayed as highlighted code in your documentation—without duplicating code.
The closest approaches in the official ecosystem are:
- Custom Component: You can create your own custom component (e.g., CodePreview.vue) and use it in your docs, but you would still need to pass both the code (as a string) and the rendered component separately, resulting in code duplication Nuxt UI Typography.
- Community Projects: The knowledge sources do not mention any community projects that solve this problem out-of-the-box.
If you want to reduce duplication, you would need to implement a custom solution, such as:
- Reading the source of a .vue file at build time and injecting it into your docs for both preview and code display.
- This approach is not covered in the official documentation or examples.
Summary:- You can create a custom component, but it won't eliminate code duplication by default. - There are no documented community projects in the provided sources that solve this in a DRY way. - Any advanced solution would require custom development beyond what is described in the official docs. If you need more details on how to create a basic custom component for previews, let me know! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
<@770620808644919307> Kapa.ai is still learning and improving, please let me know how I did by reacting below.