@lexibase/create-rdx 4.2.2 → 5.0.1

package/package.json

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

package/templates/default/README.md

@@ -16,6 +16,13 @@ pnpm dev
 
 Edit files in `docs/` to create your documentation. RDX creates and maintains
 its internal runtime in `.rdx/`.
+
+- Start with `docs/01-getting-started/writing-pages.mdx` for page setup, sidebar ordering,
+  and `rdx check`.
+- Browse `docs/02-examples/` for working Markdown components, including Steps.
+- Use **Copy this page** on any document to copy its Markdown, or open
+  `/docs/llms.txt` for an index of the published documentation.
+
 Keep custom React components in `components/` and import them from
 `rdx.config.ts` or `components/home.tsx`. The project-root `tsconfig.json` configures JSX
 and bundler-style imports for these files, including inside a monorepo.
@@ -60,7 +67,7 @@ Markdown components. Use site-root URLs for assets:
 [Download](/downloads/example.txt)
 ```
 
-See `docs/examples/images.mdx` for a working example. Do not include `/public`
+See `docs/02-examples/images.mdx` for a working example. Do not include `/public`
 in URLs and do not store private files or credentials in this directory.
 
 RDX connects `.rdx/public` to this folder automatically. Keep your files in

package/templates/default/docs/01-getting-started/configure.mdx

@@ -0,0 +1,38 @@
+---
+title: Configure your documentation site
+navTitle: Configuration
+description: Set your site identity and enable optional documentation features.
+order: 3
+---
+
+Edit `rdx.config.ts` at the root of your project. Set
+`metadata.applicationName` for the site name and `metadata.metadataBase`
+to the public origin for the sitemap and absolute URLs in Markdown exports.
+
+```ts title="rdx.config.ts"
+import { defineConfig } from '@lexibase/rdx'
+
+export default defineConfig({
+  metadata: {
+    applicationName: 'My documentation',
+    metadataBase: 'https://docs.example.com',
+  },
+  search: true,
+  TOC: true,
+  navbar: {
+    logo: '/images/rdx.svg',
+  },
+})
+```
+
+Use `search: true` to enable search in the navbar. Use `TOC: true` to show
+heading navigation on pages with enough sections. Put your logo in
+`public/images/` and set `navbar.logo` to its public path, starting with `/images/`.
+
+Set `lang` to the language of your documentation. RDX uses it for the page
+language and selects the corresponding interface messages when available.
+To add a custom landing page, create `components/home.tsx`, import it into
+`rdx.config.ts`, and set `homepage: { enabled: true, component: Home }`.
+
+See the [configuration reference](https://rdx-tool.vercel.app/docs) for more
+options, including plugins and the source edit link.

package/templates/default/docs/01-getting-started/intro.mdx

@@ -0,0 +1,21 @@
+---
+title: Introduction
+description: Start building your documentation with RDX.
+order: 1
+---
+
+RDX turns folders and `.md` or `.mdx` files into a documentation site. Start by editing
+this page or adding new pages inside `docs/`.
+
+## Start here
+
+- [Write your first page](./writing-pages.mdx) and organize the sidebar.
+- [Configure your site](./configure.mdx) with your name, logo, and navigation.
+- [Try Markdown](../02-examples/markdown.md), then explore [Callouts](../02-examples/callouts.mdx),
+  [Tabs](../02-examples/tabs.mdx), [Accordion](../02-examples/accordion.mdx), and
+  [Steps](../02-examples/steps.mdx).
+- [Share a page as Markdown](../02-examples/markdown-exports.mdx) or open the
+  documentation index at `/docs/llms.txt`.
+- Explore [code blocks](../02-examples/code-blocks.mdx),
+  [diagrams](../02-examples/diagrams.mdx), and
+  [keyboard shortcuts](../02-examples/keyboard-shortcuts.mdx).

package/templates/default/docs/01-getting-started/writing-pages.mdx

@@ -0,0 +1,58 @@
+---
+title: Writing pages
+description: Learn how to add pages and categories to your site.
+order: 2
+---
+
+## Create a page
+
+Add a `.md` or `.mdx` file inside a folder in `docs/`. Its path becomes the page URL.
+
+```folder
+docs/
+  03-guides/
+    01-deployment.md
+```
+
+This file is available at `/docs/guides/deployment`.
+
+## Organize the sidebar
+
+Top-level folders become categories. A two-digit prefix sorts folders and files
+without appearing in their URLs. Lower numbers appear first. The `order` field
+overrides the file prefix, and `navTitle` lets you shorten a sidebar label.
+
+```yaml
+---
+title: Deploy your documentation site
+description: Build your site and preview the production output.
+navTitle: Deployment
+order: 1
+highlighting: new
+---
+```
+
+All five fields are optional. `title` and `description` appear in the page
+header. Use `highlighting: new` for a blue dot or `highlighting: important`
+for an amber dot. Remove the field when the page no longer needs attention.
+
+## Validate your content
+
+Run the documentation check before deploying. It reports broken links and
+invalid content with their source locations.
+
+:::tabs
+
+### pnpm
+
+pnpm rdx check
+
+### npm
+
+npm exec -- rdx check
+
+### yarn
+
+yarn rdx check
+
+:::

package/templates/default/docs/{examples → 02-examples}/accordion.mdx

@@ -1,7 +1,7 @@
 ---
 title: Accordion
 description: Optional explanations, without crowding your documentation.
-link_position: 6
+order: 6
 ---
 
 ## Frequently asked questions
@@ -13,7 +13,7 @@ The answer continues until the next direct `###` or the closing `:::`.
 
 ### Where do I write my documentation?
 
-Create folders and `.mdx` files inside **docs/**. Each folder becomes a category
+Create folders and Markdown files inside **docs/**. Each top-level folder becomes a category
 and each file becomes a page.
 
 ### How do I preview my changes?

package/templates/default/docs/{examples → 02-examples}/callouts.mdx

@@ -1,7 +1,7 @@
 ---
 title: Callouts
 description: Notes, tips, and warnings that fit the documentation.
-link_position: 4
+order: 4
 ---
 
 ## Write a Callout

package/templates/default/docs/{examples → 02-examples}/code-blocks.mdx

@@ -1,7 +1,7 @@
 ---
 title: Code blocks
 description: Highlight code, compare changes, and draw directory trees.
-link_position: 9
+order: 9
 ---
 
 All fence options are optional. These examples show each one separately before
@@ -19,7 +19,12 @@ Hello, RDX!
 Hello, RDX!
 ```
 
-The header uses the default code label. Add a language for highlighting:
+The header uses the default code label.
+
+## Highlight a language
+
+Add a language such as `ts`, `tsx`, `json`, or `bash` after the opening fence.
+Highlighting follows your light or dark theme. Unknown languages display as plain text.
 
 ````md
 ```tsx
@@ -41,12 +46,22 @@ Place `title="filename"` after the fence language:
 
 ````md
 ```ts title="rdx.config.ts"
-const search = true
+import { defineConfig } from '@lexibase/rdx'
+
+export default defineConfig({
+  metadata: { applicationName: 'My documentation' },
+  search: true,
+})
 ```
 ````
 
 ```ts title="rdx.config.ts"
-const search = true
+import { defineConfig } from '@lexibase/rdx'
+
+export default defineConfig({
+  metadata: { applicationName: 'My documentation' },
+  search: true,
+})
 ```
 
 The title appears in the header; copying keeps only the code. Titles with spaces
@@ -107,6 +122,16 @@ const enabled = true
 console.log(enabled)
 ```
 
+## Wrap long lines
+
+On small screens, use the wrap control in the code block header to fit long lines
+within the available space. Try it on the block below. The copy button preserves
+the original indentation and line breaks.
+
+```text title="Long line"
+Keep explanations close to the example they describe, and use wrapping to read a long line on a narrow screen.
+```
+
 ## Long blocks on mobile
 
 On screens narrower than 768px, blocks taller than about 12 visible lines show

package/templates/default/docs/02-examples/colors.mdx

@@ -0,0 +1,21 @@
+---
+title: Colors
+description: Customize the accent used by links and selected documentation controls.
+order: 2
+---
+
+RDX includes a clean default theme that adapts to your system preference.
+To customize the accent, create `rdx.css` beside `rdx.config.ts` and set
+`--rdx-highlighting` for each theme:
+
+```css title="rdx.css"
+:root {
+  --rdx-highlighting: #1d4ed8;
+}
+
+.dark {
+  --rdx-highlighting: #93c5fd;
+}
+```
+
+Use a color that remains legible against the background in each theme.

package/templates/default/docs/{examples → 02-examples}/diagrams.mdx

@@ -1,7 +1,7 @@
 ---
 title: Diagrams
 description: Turn Mermaid definitions into flowcharts, sequences, and other diagrams.
-link_position: 10
+order: 10
 ---
 
 ## Write a diagram

package/templates/default/docs/{examples → 02-examples}/images.mdx

@@ -1,7 +1,7 @@
 ---
 title: Images and downloads
 description: Serve files from your project's public directory.
-link_position: 3
+order: 3
 ---
 
 ## Images

package/templates/default/docs/{examples → 02-examples}/keyboard-shortcuts.mdx

@@ -1,12 +1,12 @@
 ---
 title: Keyboard shortcuts
 description: Describe keys and shortcut combinations with Markdown.
-link_position: 8
+order: 8
 ---
 
 ## Display a key
 
-Write `:kbd[Key]` in your `.mdx` pages. No import or plugin is required:
+Write `:kbd[Key]` in a Markdown or MDX page:
 
 Press :kbd[Esc] to close a dialog or :kbd[Enter] to confirm.
 
@@ -18,7 +18,7 @@ Press :kbd[Esc] to close a dialog or :kbd[Enter] to confirm.
 
 Write the complete combination inside one directive, separating keys with `+`:
 
-Press :kbd[Ctrl + K] to open search.
+If search is enabled, press :kbd[Ctrl + K] to open it.
 
 ```md
 Press :kbd[Ctrl + K] to open search.

package/templates/default/docs/{examples → 02-examples}/links.mdx

@@ -1,17 +1,17 @@
 ---
 title: Document links
 description: Link to documentation files using their relative paths.
-link_position: 7
+order: 7
 ---
 
 ## Link to a page
 
-Read the [introduction](../init/intro.mdx) or learn how to
-[create a page](../init/getting-started.mdx#create-a-page).
+Read the [introduction](../01-getting-started/intro.mdx) or learn how to
+[create a page](../01-getting-started/writing-pages.mdx#create-a-page).
 
 ```md
-[Introduction](../init/intro.mdx)
-[Create a page](../init/getting-started.mdx#create-a-page)
+[Introduction](../01-getting-started/intro.mdx)
+[Create a page](../01-getting-started/writing-pages.mdx#create-a-page)
 ```
 
 RDX resolves these paths relative to this file. When viewing a snapshot,
@@ -19,11 +19,13 @@ links stay inside that snapshot instead of switching to Current.
 
 ## Link to a section
 
-Jump to the [tables example](./markdown.mdx#tables), or return to
+Jump to the [tables example](./markdown.md#tables), or return to
 [the first section](#link-to-a-page) of this page.
 
 Markdown headings receive automatic IDs. Repeated headings get suffixes such as
-`tables-1`. Relative document links must include the `.mdx` extension.
+`tables-1`. Relative document links must include the actual `.md` or `.mdx`
+extension. Select a section heading to open its anchor and copy its URL.
+The `#` beside the title marks that link.
 
 > [!NOTE] Keep links portable
 > Use forward slashes and match the file's name and capitalization. If a destination

package/templates/default/docs/02-examples/markdown-exports.mdx

@@ -0,0 +1,24 @@
+---
+title: Markdown exports and llms.txt
+navTitle: Markdown exports
+description: Copy a page, open its Markdown source, or browse the public index.
+order: 12
+---
+
+## Copy or view a page
+
+Select **Copy this page** beside the title to copy the document as Markdown.
+Open the adjacent menu and choose **View Markdown** to read the same export in
+a new tab. The export includes the page URL and a link to its documentation index.
+
+## Find more pages
+
+Open the documentation index at `/docs/llms.txt` to find the Markdown export for
+each page. With versioning enabled, the index lists the latest active published
+edition. If you publish translations, each language has its own index.
+
+Set `metadata.metadataBase` in `rdx.config.ts` to your site's public URL to use
+absolute links in the index and exported documents.
+
+The export adds `lastUpdated` in `YYYY-MM-DD` format when the date is available
+from Git history or captured in a version snapshot.

package/templates/default/docs/{examples/markdown.mdx → 02-examples/markdown.md}

@@ -1,7 +1,7 @@
 ---
 title: Markdown
 description: A small Markdown and MDX example.
-link_position: 1
+order: 1
 ---
 
 ## Markdown works
@@ -41,7 +41,7 @@ Wider tables scroll horizontally on small screens without widening the page.
 
 > Keep explanations close to the content they describe.
 >
-> A quotation can contain **formatted text**, [links](/docs/init/intro), and `inline code`.
+> A quotation can contain **formatted text**, [links](/docs/getting-started/intro), and `inline code`.
 
 You can also use ~~strikethrough~~ text.
 

package/templates/default/docs/02-examples/steps.mdx

@@ -0,0 +1,57 @@
+---
+title: Steps
+description: Present a procedure one step at a time in an interactive card.
+order: 11
+---
+
+## Try Steps
+
+::::steps
+
+### Start the preview
+
+:::tabs
+
+### pnpm
+
+pnpm dev
+
+### npm
+
+npm run dev
+
+### yarn
+
+yarn dev
+
+:::
+
+### Edit a page
+
+Open a Markdown file in `docs/`, make a change, and save it.
+
+### Verify the result
+
+Visit the page in your browser and check that the change appears.
+
+::::
+
+## Write your own Steps
+
+Open with `:::steps` and use `###` for each step title. Readers move between
+steps with **Previous** and **Next**. When nesting a `:::tabs` block, open
+and close Steps with four colons, as in the example above.
+
+```md
+:::steps
+
+### Start the preview
+
+Open the local development URL.
+
+### Verify the result
+
+Check the changed page in your browser.
+
+:::
+```

package/templates/default/docs/{examples → 02-examples}/tabs.mdx

@@ -1,7 +1,7 @@
 ---
 title: Tabs
 description: Accessible tabs for related examples and documentation.
-link_position: 5
+order: 5
 ---
 
 ## Choose your package manager

package/templates/default/package.json

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

package/templates/default/docs/examples/_category.json

@@ -1,4 +0,0 @@
-{
-  "title": "Examples",
-  "sidebar_position": 2
-}

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

@@ -1,7 +0,0 @@
----
-title: Colors
-description: An example page inside a second category.
-link_position: 2
----
-
-RDX includes a clean default theme that adapts to your system preference.

package/templates/default/docs/init/_category.json

@@ -1,4 +0,0 @@
-{
-  "title": "Getting started",
-  "sidebar_position": 1
-}

package/templates/default/docs/init/getting-started.mdx

@@ -1,17 +0,0 @@
----
-title: Getting started
-description: Learn how to add pages and categories to your site.
-link_position: 2
----
-
-## Create a page
-
-Add an `.mdx` file inside a folder in `docs/`. Its path becomes the page URL.
-
-```text
-docs/
-└── guides/
-    └── deployment.mdx
-```
-
-This file is available at `/docs/guides/deployment`.

package/templates/default/docs/init/intro.mdx

@@ -1,10 +0,0 @@
----
-title: Introduction
-description: Start building your documentation with RDX.
-link_position: 1
----
-
-# Welcome to your documentation
-
-RDX turns folders and `.md` or `.mdx` files into a documentation site. Start by editing
-this page or adding new pages inside `docs/`.