@lexibase/create-rdx 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/create-rdx",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Create a new RDX documentation project.",
   "license": "MIT",
   "bin": {

package/templates/default/docs/examples/accordion.mdx

@@ -1,69 +1,94 @@
 ---
 title: Accordion
-description: Keep optional explanations close without crowding the page.
+description: Optional explanations, without crowding your documentation.
 link_position: 6
 ---
 
 ## Frequently asked questions
 
-Use Enter or Space to expand an item. Tab moves between questions and links.
-One item opens at a time; selecting it again closes it.
+Wrap questions in `:::accordion` and start each item with `### Question`.
+The answer continues until the next direct `###` or the closing `:::`.
 
-<Accordion>
-  <AccordionItem value="content">
-    <AccordionTrigger>Where do I write my documentation?</AccordionTrigger>
-    <AccordionContent>
+::::accordion
+
+### Where do I write my documentation?
 
 Create folders and `.mdx` files inside **docs/**. Each folder becomes a category
 and each file becomes a page.
 
-Read the [introduction](/docs/init/intro) to get started.
+### How do I preview my changes?
+
+Start the development server from your documentation project root:
 
-    </AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="preview">
-    <AccordionTrigger>How do I preview my changes?</AccordionTrigger>
-    <AccordionContent>
+:::tabs
 
-Run the development server:
+### pnpm
 
-```bash
 pnpm dev
+
+### npm
+
+npm run dev
+
+### yarn
+
+yarn dev
+
+:::
+
+> [!TIP] Live updates
+> Keep the server running while editing your documentation.
+
+::::
+
+## Write an Accordion
+
+```md
+:::accordion
+
+### Where do I write my docs?
+
+Create folders and Markdown files inside **docs/**.
+
+### How do I preview my changes?
+
+Start the development server from your documentation project root.
+
+:::
 ```
 
-<Callout variant="tip" title="Live updates">
+No import or plugin is required. Items start closed, and opening one closes the
+previous item in the same group. Use Enter or Space to toggle and Tab to move
+between questions and links. Keep essential steps visible rather than hiding
+the whole guide in panels.
+
+## Nest components
 
-Keep the server running while editing your documentation.
+Answers support Markdown and RDX components. When Tabs are inside an Accordion,
+open the outer Accordion with **four colons** (`::::accordion`) and close it with
+`::::`. The inner Tabs use **three colons** (`:::tabs`) and close with `:::`.
+The extra colon keeps the inner closing fence from closing the outer component.
+For each additional nesting level, use one more colon on the outer container:
 
-</Callout>
+```md
+::::accordion
 
-    </AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="disabled" disabled>
-    <AccordionTrigger>Disabled example</AccordionTrigger>
-    <AccordionContent>This item demonstrates the disabled state.</AccordionContent>
-  </AccordionItem>
-</Accordion>
+### Which environment should I use?
 
-## Production checklist
+:::tabs
 
-Opening an answer closes the previous one in the same group.
+### Development
 
-<Accordion>
-  <AccordionItem value="build">
-    <AccordionTrigger>Build for production</AccordionTrigger>
-    <AccordionContent>
+Preview changes locally.
 
-Run `pnpm build` to generate the production site.
+### Production
 
-    </AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="start">
-    <AccordionTrigger>Check the production site</AccordionTrigger>
-    <AccordionContent>
+Build and deploy the site.
 
-Run `pnpm start` after a successful build.
+:::
+
+::::
+```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+Use `####` or deeper headings for subsections inside an answer. Direct `###`
+headings define item titles in the current container.

package/templates/default/docs/examples/callouts.mdx

@@ -1,56 +1,73 @@
 ---
 title: Callouts
-description: Highlight notes, tips and important information.
+description: Notes, tips, and warnings that fit the documentation.
 link_position: 4
 ---
 
-## Highlight important information
+## Write a Callout
 
-Callouts are included in RDX. No import or plugin is required.
+Start a blockquote with `[!TYPE]`. Add an optional title on the same line and
+write the body on the following quoted lines:
 
-<Callout title="A useful note">
-
-Keep supporting information close to the documentation it explains.
-
-</Callout>
-
-<Callout variant="tip" title="A helpful tip">
-
-You can use **Markdown**, [documentation links](/docs/init/intro), and `inline code` inside a callout.
-
-</Callout>
+```md
+> [!TIP] A useful shortcut
+> Use **Markdown**, inline code, links, and lists in the body.
+```
 
-<Callout variant="success" title="Ready to go">
+> [!TIP] A useful shortcut
+> Use **Markdown**, inline code, links, and lists in the body.
 
-Your documentation is ready to share.
+No import or plugin is required. Choose one of the five uppercase markers:
 
-</Callout>
+## Try the variants
 
-<Callout variant="warning" title="Before updating">
+> [!NOTE] A useful note
+> Explain a detail without interrupting the main instructions.
 
-- Read the release notes.
-- Test your changes before deploying.
+> [!TIP] Keep it short
+> Use a Callout when the context changes how the reader should proceed.
 
-</Callout>
+> [!SUCCESS] Ready to continue
+> Your documentation is ready for the next step.
 
-<Callout variant="danger" title="Irreversible action">
+> [!WARNING] Before updating
+> Read the release notes and validate your production build.
 
-Deleting the source files permanently removes their content.
+> [!DANGER] Review destructive changes
+> Confirm the exact files before deleting source content.
 
-</Callout>
+```md
+> [!NOTE] A useful note
+> Explain a detail.
 
-<Callout>
+> [!TIP] Keep it short
+> Share a useful shortcut.
 
-A title is optional. The default variant is `note`.
+> [!SUCCESS] Ready to continue
+> Confirm a successful step.
 
-</Callout>
+> [!WARNING] Before updating
+> Read the release notes.
 
-## Syntax
+> [!DANGER] Review destructive changes
+> Confirm the exact files before deleting them.
+```
 
-```mdx
-<Callout variant="warning" title="Before updating">
+## Optional titles and rich content
 
-Test your changes before deploying.
+Leave the title out for a compact note. Continue the quote with a blank quoted
+line before a list or another paragraph:
 
-</Callout>
+```md
+> [!NOTE]
+> Before continuing:
+>
+> - Review your configuration.
+> - Run a production build.
 ```
+
+> [!NOTE]
+> Before continuing:
+>
+> - Review your configuration.
+> - Run a production build.

package/templates/default/docs/examples/code-blocks.mdx

@@ -4,6 +4,116 @@ description: Highlight code, compare changes, and draw directory trees.
 link_position: 9
 ---
 
+All fence options are optional. These examples show each one separately before
+combining them.
+
+## Plain code
+
+````md
+```
+Hello, RDX!
+```
+````
+
+```
+Hello, RDX!
+```
+
+The header uses the default code label. Add a language for highlighting:
+
+````md
+```tsx
+export function Welcome() {
+  return <h1>Hello, RDX!</h1>
+}
+```
+````
+
+```tsx
+export function Welcome() {
+  return <h1>Hello, RDX!</h1>
+}
+```
+
+## Show a filename
+
+Place `title="filename"` after the fence language:
+
+````md
+```ts title="rdx.config.ts"
+const search = true
+```
+````
+
+```ts title="rdx.config.ts"
+const search = true
+```
+
+The title appears in the header; copying keeps only the code. Titles with spaces
+use quotes, such as `title="Install dependencies"`.
+
+## Number lines
+
+Add only `lineNumbers` to start at 1, with no title or custom starting value:
+
+````md
+```tsx lineNumbers
+export function Welcome() {
+  return <h1>Hello, RDX!</h1>
+}
+```
+````
+
+```tsx lineNumbers
+export function Welcome() {
+  return <h1>Hello, RDX!</h1>
+}
+```
+
+Omit the flag to keep numbers hidden. Copying excludes the line numbers.
+
+## Set the starting line
+
+Use `startLine` alongside `lineNumbers` for a fragment of a larger file:
+
+````md
+```ts lineNumbers startLine=20
+const enabled = true
+console.log(enabled)
+```
+````
+
+```ts lineNumbers startLine=20
+const enabled = true
+console.log(enabled)
+```
+
+`startLine` is a positive integer. Omit it to start at 1. It sets the starting
+value without enabling numbering by itself.
+
+## Combine options
+
+Add a title when a filename helps explain the fragment:
+
+````md
+```ts title="example.ts" lineNumbers startLine=20
+const enabled = true
+console.log(enabled)
+```
+````
+
+```ts title="example.ts" lineNumbers startLine=20
+const enabled = true
+console.log(enabled)
+```
+
+## Long blocks on mobile
+
+On screens narrower than 768px, blocks taller than about 12 visible lines show
+an automatic preview. Use **Show more** to expand and **Show less** to collapse.
+Short blocks and desktop views remain fully visible. Copying always includes
+the complete block, including content outside the preview.
+
 ## Compare changes
 
 Use a `diff` fence. Prefix removed lines with `-`, added lines with `+`,
@@ -15,6 +125,18 @@ and unchanged lines with a space. The copy button copies the patch as shown.
  console.log(search)
 ```
 
+## Mermaid diagrams
+
+Use a `mermaid` fence to render a diagram. The header can show an optional title,
+copy the definition, switch between diagram and source, or open a larger view:
+
+```mermaid title="Documentation flow"
+flowchart LR
+    A[Write Markdown] --> B[Preview] --> C[Publish]
+```
+
+See [Diagrams](./diagrams.mdx) for syntax examples and accessibility.
+
 ## Draw a folder tree
 
 Use a `folder` fence with two spaces per level. End folder names with `/`.
@@ -33,5 +155,31 @@ my-docs/
   rdx.config.ts
 ```
 
-Use `text` instead to display a diagram you have already drawn. Long lines
-scroll inside the block. The icon in the header copies the rendered tree.
+Folder names ending in `/` receive a folder icon. File icons follow their
+extension, with a generic file icon for other names.
+
+## Type ASCII branches
+
+Use `|-` for `├──`, `|_` for `└──`, and `|` for `│` in the tree prefixes:
+
+````md
+```folder title="Project files"
+my-docs/
+|- docs/
+|   |_ intro.mdx
+|- package.json
+|_ logo.svg
+```
+````
+
+```folder title="Project files"
+my-docs/
+|- docs/
+|   |_ intro.mdx
+|- package.json
+|_ logo.svg
+```
+
+Leave a space between each branch marker and the name. Existing Unicode trees
+also work. Copying produces the text diagram without icons; a `text` fence
+preserves the original ASCII characters. Long lines scroll inside the block.

package/templates/default/docs/examples/diagrams.mdx

@@ -0,0 +1,95 @@
+---
+title: Diagrams
+description: Turn Mermaid definitions into flowcharts, sequences, and other diagrams.
+link_position: 10
+---
+
+## Write a diagram
+
+Use a fenced code block with `mermaid` as its language. RDX renders the diagram
+inside the shared code-block frame:
+
+````md
+```mermaid title="Documentation flow"
+flowchart TD
+    A[Write Markdown] --> B[Preview locally]
+    B --> C{Ready?}
+    C -->|Yes| D[Build and deploy]
+    C -->|No| A
+```
+````
+
+```mermaid title="Documentation flow"
+flowchart TD
+    A[Write Markdown] --> B[Preview locally]
+    B --> C{Ready?}
+    C -->|Yes| D[Build and deploy]
+    C -->|No| A
+```
+
+No import or plugin is required. The `title` is optional. Diagram colors follow
+the site's light or dark theme.
+
+## Explore and copy
+
+Use the header buttons to show the diagram's source, return to the diagram,
+open a larger view, or copy the original Mermaid definition. The larger view
+scrolls when a diagram exceeds the screen. Press Escape to close it and return
+to the expand button.
+
+The source view also supports the optional `lineNumbers` and `startLine` fence
+options. On mobile, use its wrap-lines button for long definitions.
+
+Mermaid loads when a diagram block approaches the visible area. Rendering runs
+in the browser; before it finishes, or with JavaScript disabled, the definition
+remains readable. If a definition is invalid, the block displays a message and
+keeps its source available. Keep definitions within 50,000 characters and
+flowcharts within 500 edges.
+
+## Sequence diagrams
+
+Mermaid supports different diagram types through the same fence. For example:
+
+```mermaid title="Documentation request"
+sequenceDiagram
+    accTitle: Loading a documentation page
+    accDescr: A reader requests a page and the site returns the document.
+    participant Reader
+    participant Site
+    Reader->>Site: Open a documentation page
+    Site-->>Reader: Return the document
+```
+
+````md
+```mermaid title="Documentation request"
+sequenceDiagram
+    accTitle: Loading a documentation page
+    accDescr: A reader requests a page and the site returns the document.
+    participant Reader
+    participant Site
+    Reader->>Site: Open a documentation page
+    Site-->>Reader: Return the document
+```
+````
+
+Use Mermaid's `accTitle` and `accDescr` to describe your diagram for screen
+readers. A fence `title` supplies the image's accessible name when present,
+followed by `accDescr` when provided.
+
+## Tree-shaped flows
+
+Use branches to describe a process or a hierarchy:
+
+```mermaid title="Documentation sections"
+flowchart TD
+    Docs[Documentation] --> Start[Getting started]
+    Docs --> Writing[Writing documentation]
+    Docs --> Features[Features]
+    Writing --> Markdown[Markdown]
+    Writing --> Components[Components]
+    Features --> Search[Search]
+    Features --> Versions[Versioning]
+```
+
+For directory structures, use a [folder code block](./code-blocks.mdx#draw-a-folder-tree).
+For more diagram types and syntax, see the [Mermaid documentation](https://mermaid.js.org/intro/).

package/templates/default/docs/examples/keyboard-shortcuts.mdx

@@ -1,31 +1,45 @@
 ---
 title: Keyboard shortcuts
-description: Display keys and shortcut combinations with Kbd.
+description: Describe keys and shortcut combinations with Markdown.
 link_position: 8
 ---
 
-## Single keys
+## Display a key
 
-Press <Kbd>Enter</Kbd> to confirm or <Kbd>Esc</Kbd> to close a dialog.
+Write `:kbd[Key]` in your `.mdx` pages. No import or plugin is required:
 
-## Shortcut reference
+Press :kbd[Esc] to close a dialog or :kbd[Enter] to confirm.
 
-Use `KbdGroup` to keep keys together when describing your application's shortcuts:
+```md
+Press :kbd[Esc] to close a dialog or :kbd[Enter] to confirm.
+```
+
+## Write a shortcut
+
+Write the separator as ordinary text between the keys:
 
-| Action | Shortcut |
-| :----- | :------- |
-| Search | <KbdGroup><Kbd>Ctrl</Kbd>+<Kbd>K</Kbd></KbdGroup> |
-| Save | <KbdGroup><Kbd>Ctrl</Kbd>+<Kbd>S</Kbd></KbdGroup> |
-| Close | <Kbd>Esc</Kbd> |
+Press :kbd[Ctrl] + :kbd[K] to open search.
 
-```mdx
-<KbdGroup aria-label="Control plus K">
-  <Kbd>Ctrl</Kbd>+<Kbd>K</Kbd>
-</KbdGroup>
+```md
+Press :kbd[Ctrl] + :kbd[K] to open search.
 ```
 
-For a macOS shortcut:
+## Shortcut reference tables
+
+| Action         | Shortcut             |
+| :------------- | :------------------- |
+| Open search    | :kbd[Ctrl] + :kbd[K] |
+| Save           | :kbd[Ctrl] + :kbd[S] |
+| Close a dialog | :kbd[Esc]            |
+
+```md
+| Action         | Shortcut             |
+| :------------- | :------------------- |
+| Open search    | :kbd[Ctrl] + :kbd[K] |
+| Save           | :kbd[Ctrl] + :kbd[S] |
+| Close a dialog | :kbd[Esc]            |
+```
 
-<KbdGroup aria-label="Command plus K">
-  <Kbd aria-label="Command">⌘</Kbd>+<Kbd>K</Kbd>
-</KbdGroup>
+These shared shadcn/ui components render semantic `<kbd>` elements and follow
+the site's light and dark themes. Use them to describe shortcuts supported by
+your application.

package/templates/default/docs/examples/links.mdx

@@ -25,12 +25,9 @@ Jump to the [tables example](./markdown.mdx#tables), or return to
 Markdown headings receive automatic IDs. Repeated headings get suffixes such as
 `tables-1`. Relative document links must include the `.mdx` extension.
 
-<Callout title="Keep links portable">
-
-Use forward slashes and match the file's name and capitalization. If a destination
-does not exist in the current version, RDX reports the source file and link to fix.
-
-</Callout>
+> [!NOTE] Keep links portable
+> Use forward slashes and match the file's name and capitalization. If a destination
+> does not exist in the current version, RDX reports the source file and link to fix.
 
 ## Assets and external links
 

package/templates/default/docs/examples/markdown.mdx

@@ -16,23 +16,23 @@ const framework = 'RDX'
 
 ## Tables
 
-| Feature | Available |
-| :------ | --------: |
-| Markdown tables | Yes |
-| Callouts | Yes |
-| Code blocks | Yes |
-| Blockquotes | Yes |
+| Feature         | Available |
+| :-------------- | --------: |
+| Markdown tables |       Yes |
+| Callouts        |       Yes |
+| Code blocks     |       Yes |
+| Blockquotes     |       Yes |
 
 ### Five-column comparison
 
 Wider tables scroll horizontally on small screens without widening the page.
 
-| Feature | Description | Status | Plugin | Example |
-| :------ | :---------- | :----: | :----: | :------ |
-| Markdown | Write headings, lists, and paragraphs | Included | Not required | `## Heading` |
-| Callout | Highlight contextual information | Included | Not required | `<Callout>` |
-| Code block | Display source code with a copy button | Included | Not required | `pnpm dev` |
-| Blockquote | Quote a passage or explanation | Included | Not required | `> A quotation` |
+| Feature    | Description                            |  Status  |    Plugin    | Example         |
+| :--------- | :------------------------------------- | :------: | :----------: | :-------------- |
+| Markdown   | Write headings, lists, and paragraphs  | Included | Not required | `## Heading`    |
+| Callout    | Highlight contextual information       | Included | Not required | `> [!NOTE]`     |
+| Code block | Display source code with a copy button | Included | Not required | `pnpm dev`      |
+| Blockquote | Quote a passage or explanation         | Included | Not required | `> A quotation` |
 
 ## Task lists
 

package/templates/default/docs/examples/tabs.mdx

@@ -1,72 +1,111 @@
 ---
 title: Tabs
-description: Group related examples without leaving the page.
+description: Accessible tabs for related examples and documentation.
 link_position: 5
 ---
 
 ## Choose your package manager
 
-Tabs are included in RDX. No import or plugin is required.
-Use the arrow keys to move between tabs and Enter or Space to select one.
+Wrap related examples in `:::tabs`. Each direct `### Title` creates a tab;
+its content continues until the next title or the closing `:::`.
+The first enabled tab is selected initially. No import or plugin is required.
+
+:::tabs
 
-<Tabs defaultValue="pnpm">
-  <TabsList aria-label="Package manager">
-    <TabsTrigger value="npm">npm</TabsTrigger>
-    <TabsTrigger value="pnpm">pnpm</TabsTrigger>
-    <TabsTrigger value="yarn">yarn</TabsTrigger>
-  </TabsList>
-  <TabsContent value="npm">
+### pnpm
 
-Install dependencies with **npm**:
+pnpm install
+
+### npm
 
-```bash
 npm install
-```
 
-  </TabsContent>
-  <TabsContent value="pnpm">
+### yarn
+
+yarn install
+
+:::
+
+## Write your own tabs
 
-Install dependencies with **pnpm**:
+```md
+:::tabs
+
+### pnpm
 
-```bash
 pnpm install
-```
 
-  </TabsContent>
-  <TabsContent value="yarn">
+### npm
+
+npm install
 
-Install dependencies with **yarn**:
+### yarn
 
-```bash
 yarn install
+
+:::
 ```
 
-  </TabsContent>
-</Tabs>
+Use the arrow keys to move between tabs and Enter or Space to select one.
+The icon-only copy button copies the selected panel as plain text, including
+complete code blocks. Each group maintains its own selection.
+
+## Combine with Markdown
+
+Panels support paragraphs, lists, code blocks, Callouts and other RDX components.
+Use `####` or deeper headings for subsections inside a panel. Direct `###`
+headings are reserved for tab labels within the container.
 
-## Keep related information together
+:::tabs
+
+### Development
+
+> [!TIP] Live updates
+> Keep the development server running while editing your documentation.
+
+### Production
+
+1. Build your documentation.
+2. Start the production server to check the result.
+
+:::
+
+## Disable a tab
+
+Add `{disabled}` after the tab title. The label stays visible and the tab cannot
+be activated. The first enabled tab is selected automatically; each group must
+have at least one enabled tab.
+
+```md
+:::tabs
+
+### pnpm
+
+pnpm dev
+
+### npm {disabled}
+
+npm run dev
+
+### yarn {disabled}
+
+yarn dev
+
+:::
+```
 
-Each group works independently. Panels can contain normal Markdown and RDX components.
+:::tabs
 
-<Tabs defaultValue="development">
-  <TabsList aria-label="Environment">
-    <TabsTrigger value="development">Development</TabsTrigger>
-    <TabsTrigger value="production">Production</TabsTrigger>
-    <TabsTrigger value="preview" disabled>Disabled example</TabsTrigger>
-  </TabsList>
-  <TabsContent value="development">
+### pnpm
 
-<Callout variant="tip" title="Live updates">
+pnpm dev
 
-Run `pnpm dev` and edit your documentation to see changes locally.
+### npm {disabled}
 
-</Callout>
+npm run dev
 
-  </TabsContent>
-  <TabsContent value="production">
+### yarn {disabled}
 
-1. Run `pnpm build`.
-2. Run `pnpm start` to check the production site.
+yarn dev
 
-  </TabsContent>
-</Tabs>
+:::

package/templates/default/package.json

@@ -9,7 +9,7 @@
     "start": "rdx start"
   },
   "dependencies": {
-    "@lexibase/rdx": "3.0.0",
+    "@lexibase/rdx": "3.1.0",
     "next": "^16.4.2",
     "react": "19.3.1",
     "react-dom": "19.3.1"