improve content

Author: HugoRCD

content/2.essentials/1.markdown-syntax.md

@@ -6,6 +6,8 @@ navigation.icon: i-lucide-heading-1
 
 ## Titles
 
+Use titles to introduce main sections. They structure your documentation and help users navigate content.
+
 ::code-preview{class="[&>div]:*:my-0"}
 
 ## Titles
@@ -20,6 +22,8 @@ navigation.icon: i-lucide-heading-1
 
 ### Subtitles
 
+Use subtitles to divide sections further. They create a more detailed content hierarchy for better readability.
+
 ::code-preview{class="[&>div]:*:my-0"}
 
 ### Subtitles
@@ -46,15 +50,15 @@ Nuxt UI Pro supports most Markdown formatting options.
 | Italic | `*italic*`   | *Italic*   |
 | Strike | `~~strike~~` | ~~Strike~~ |
 
-You can also combine them:
+Combine formatting for richer text styles and visual emphasis.
 
 | Style         | How to use          | Result            |
 |---------------|---------------------|-------------------|
 | Bold Italic   | `**_bold italic_**` | **_Bold Italic_** |
 | Bold Strike   | `~~**bold**~~`      | ~~**Bold**~~      |
 | Italic Strike | `~~*italic*~~`      | ~~*Italic*~~      |
 
-You need to use HTML to write superscript and subscript text. Add `sup` or `sub` around your text to create superscript or subscript.
+For exponents, indices, or mathematical notations, use HTML `<sup>` and `<sub>` tags.
 
 | Style       | How to use               | Result                 |
 |-------------|--------------------------|------------------------|
@@ -63,6 +67,7 @@ You need to use HTML to write superscript and subscript text. Add `sup` or `sub`
 
 ## Links
 
+Links connect different parts of your documentation and external resources, essential for user navigation and providing references.
 To create a link, wrap the link text in brackets `[]()`.
 
 ::code-preview{class="[&>div]:*:my-0"}
@@ -77,9 +82,9 @@ To create a link, wrap the link text in brackets `[]()`.
 
 ::
 
-### Links to other pages
+### Internal links
 
-Links to other pages of your documentation needs to be root-relative. For example, if you have a page called `getting-started/installation`, the link to that page should be `[Installation](/getting-started/installation)`.
+For linking within your documentation, use root-relative paths like `/getting-started/installation`.
 
 ::code-preview{class="[&>div]:*:my-0"}
 
@@ -95,9 +100,11 @@ Links to other pages of your documentation needs to be root-relative. For exampl
 
 ## Lists
 
+Organize related items in a structured, readable format. Markdown supports unordered, ordered, and nested lists for various content needs.
+
 ### Unordered
 
-To create an unordered list, start each item with a `-`.
+Use unordered lists for items without a specific sequence. Start each item with a `-` symbol.
 
 ::code-preview{class="[&>div]:*:my-0"}
 
@@ -117,7 +124,7 @@ To create an unordered list, start each item with a `-`.
 
 ### Ordered
 
-To create an ordered list, start each item with a number.
+Use ordered lists when item order matters, like steps in a process. Start each item with a number.
 
 ::code-preview{class="[&>div]:*:my-0"}
 
@@ -137,7 +144,7 @@ To create an ordered list, start each item with a number.
 
 ### Nested
 
-To create a nested list, indent each item with four spaces.
+Create hierarchical lists with sub-items for complex structures. Indent sub-items by four spaces for nesting.
 
 ::code-preview{class="[&>div]:*:my-0"}
 
@@ -159,7 +166,7 @@ To create a nested list, indent each item with four spaces.
 
 ## Tables
 
-To create a table, use three or more hyphens (`---`) to separate each column.
+Present structured data in rows and columns clearly. Tables are ideal for comparing data or listing properties.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}
 
@@ -183,9 +190,11 @@ To create a table, use three or more hyphens (`---`) to separate each column.
 
 ## Blockquotes
 
+Highlight important quotations, citations, or emphasized text. Blockquotes visually distinguish quoted content.
+
 ### Singleline
 
-To create a blockquote, add a `>` in front of a paragraph.
+Single-line blockquotes are best for short, impactful quotes or citations that fit within a single line. To create a single-line blockquote, add a `>` in front of a paragraph. Ideal for short and impactful quotes.
 
 ::code-preview{class="[&>div]:*:my-0"}
 
@@ -201,6 +210,8 @@ To create a blockquote, add a `>` in front of a paragraph.
 
 ### Multiline
 
+Multi-line blockquotes are suitable for longer quotes or when you need to include multiple paragraphs within a single quotation.
+
 ::code-preview{class="[&>div]:*:my-0"}
 
 > Nuxt UI Pro is a collection of Vue components, composables and utils built on top of Nuxt UI, oriented on structure and layout and designed to be used as building blocks for your app.

content/2.essentials/2.code-blocks.md

@@ -8,7 +8,7 @@ navigation.icon: i-lucide-code-xml
 
 ### Inline Code
 
-To display a word or phrase as code, enclose it in backticks (\`).
+Use inline code to display code snippets within text paragraphs. It's ideal for referencing code elements directly in sentences.
 
 ::code-preview{class="[&>div]:*:my-0"}
 
@@ -24,7 +24,7 @@ To display a word or phrase as code, enclose it in backticks (\`).
 
 ### Code Blocks
 
-To display a block of code, with syntax highlighting, use three backticks (\`\`\`).
+Use code blocks to display multi-line code snippets with syntax highlighting. Code blocks are essential for presenting code examples clearly.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}
 
@@ -47,6 +47,7 @@ export default defineNuxtConfig({
 ::
 
 When writing a code-block, you can specify a filename that will be displayed on top of the code block. An icon will be automatically displayed based on the extension or the name.
+Filenames help users understand the code's location and purpose within a project.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}
 
@@ -106,6 +107,7 @@ export default defineAppConfig({
 #### Highlight Line
 
 To highlight lines of code, add `{}` around the line numbers you want to highlight.
+Line highlighting is useful for focusing users on important parts of code examples.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}
 
@@ -142,7 +144,7 @@ export default defineAppConfig({
 
 ### CodeGroup
 
-Wrap your code-blocks around a `code-group` component to group them together in a tabbed interface.
+Group code blocks in tabs using `code-group`. `code-group` is perfect for showing code examples in multiple languages or package managers.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}
 
@@ -198,7 +200,7 @@ Like the `ProsePre` component, the `CodeGroup` handles filenames, icons and copy
 
 ### CodeTree
 
-Wrap your code-blocks with a `code-tree` component in any particular order to display a tree view of your files.
+Display code blocks in a file tree view using `code-tree`. `code-tree` is excellent for showcasing project structures and file relationships.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}
 
@@ -362,7 +364,8 @@ Learn more about the `code-tree` component.
 
 ### `CodePreview`
 
-To display a code block with he's preview, use the `code-preview` component. Write the code to be previewed in a the `default` slot and the actual code in the `code` slot.
+Use `code-preview` to show code output alongside the code. `code-preview` is ideal for interactive examples and demonstrating code results.
+Write the code to be previewed in a the `default` slot and the actual code in the `code` slot.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full" label="Preview"}
 
@@ -394,7 +397,7 @@ To display a code block with he's preview, use the `code-preview` component. Wri
 
 ### `CodeCollapse`
 
-Use the `code-collapse` component to display a long code block in a collapsible format.
+Use `code-collapse` for long code blocks to keep pages clean. `code-collapse` allows users to expand code blocks only when needed, improving readability.
 
 ::code-preview{class="[&>div]:*:my-0 [&>div]:*:w-full"}