create-rspress 2.0.12 → 2.0.14

package/README.md

@@ -16,10 +16,25 @@ npx create-rspress --dir my-project
 # Using abbreviations
 npx create-rspress -d my-project
 
-# Scaffold with the custom theme template
-npx create-rspress --dir my-project --template custom-theme
+# Scaffold with the basic theme template
+npx create-rspress --dir my-project --template basic-theme
+
+# Scaffold with the multilingual template
+npx create-rspress --dir my-project --template i18n
+
+# Scaffold with the multilingual theme template
+npx create-rspress --dir my-project --template i18n-theme
 ```
 
+Available templates:
+
+| Template      | Description                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| `basic`       | Creates a minimal Rspress documentation site with the default theme.        |
+| `basic-theme` | Creates a single-language site with a `theme` folder for customization.     |
+| `i18n`        | Creates a multilingual documentation site with English and Chinese content. |
+| `i18n-theme`  | Creates a multilingual site with a `theme` folder for customization.        |
+
 ## Documentation
 
 https://rspress.rs/

package/dist/index.js

@@ -4,28 +4,50 @@ import { checkCancel, create, select as external_create_rstack_select } from "cr
 const src_dirname = node_path.dirname(fileURLToPath(import.meta.url));
 const templates = [
     'basic',
-    'custom-theme'
+    'basic-theme',
+    'i18n',
+    'i18n-theme'
 ];
+function isTemplateName(templateName) {
+    return templates.includes(templateName);
+}
 async function getTemplateName(argv) {
     if (argv.template) {
-        if (templates.includes(argv.template)) return argv.template;
+        if (isTemplateName(argv.template)) return argv.template;
         throw new Error(`Invalid template "${argv.template}". Expected one of: ${templates.join(', ')}.`);
     }
-    return checkCancel(await external_create_rstack_select({
-        message: 'Would you like to customize the theme styles?',
-        initialValue: 'custom-theme',
+    const i18nChoice = checkCancel(await external_create_rstack_select({
+        message: 'Choose documentation language setup',
+        initialValue: 'basic',
         options: [
             {
-                value: 'custom-theme',
-                label: 'Yes, set up a "theme" folder for customization',
-                hint: 'Modify styles and components later.'
+                value: 'basic',
+                label: 'Single language',
+                hint: 'docs'
             },
             {
-                value: 'basic',
-                label: 'No, use the default theme'
+                value: 'i18n',
+                label: 'Multilingual',
+                hint: 'docs/en, docs/zh'
             }
         ]
     }));
+    const themeChoice = checkCancel(await external_create_rstack_select({
+        message: 'Choose theme customization setup',
+        initialValue: 'with-theme',
+        options: [
+            {
+                value: 'with-theme',
+                label: 'Custom theme',
+                hint: 'theme/'
+            },
+            {
+                value: 'default-theme',
+                label: 'Default theme'
+            }
+        ]
+    }));
+    return 'with-theme' === themeChoice ? `${i18nChoice}-theme` : i18nChoice;
 }
 function mapESLintTemplate() {
     return 'react-ts';
@@ -36,9 +58,6 @@ function mapRslintTemplate() {
 create({
     root: node_path.resolve(src_dirname, '..'),
     name: 'rspress',
-    skipFiles: [
-        'template-placeholder'
-    ],
     templates: [
         ...templates
     ],
@@ -55,7 +74,7 @@ create({
             value: 'rspress-custom-theme',
             label: 'Rspress custom theme',
             source: 'rstackjs/agent-skills',
-            when: (templateName)=>'custom-theme' === templateName
+            when: ({ templateName })=>templateName.endsWith('-theme')
         },
         {
             value: "rspress-description-generator",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rspress",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "description": "Create a new Rspress project",
   "homepage": "https://rspress.rs",
   "repository": {
@@ -18,16 +18,16 @@
     "create-rspress": "./bin.js"
   },
   "files": [
-    "template-*",
+    "template-*/**",
     "dist",
     "bin.js"
   ],
   "dependencies": {
-    "create-rstack": "2.1.2"
+    "create-rstack": "2.1.3"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.57.7",
-    "@rslib/core": "0.21.5",
+    "@rslib/core": "0.22.0",
     "@types/node": "^22.8.1",
     "rsbuild-plugin-publint": "^0.3.4",
     "typescript": "^6.0.3"
@@ -40,8 +40,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "rslib build",
-    "dev": "rslib build -w",
+    "build": "node ./scripts/generate-theme-templates.mjs && rslib build",
+    "dev": "node ./scripts/generate-theme-templates.mjs && rslib build -w",
     "start": "node ./dist/index.js"
   }
 }

package/template-basic/docs/_nav.json

@@ -0,0 +1,16 @@
+[
+  {
+    "text": "Guide",
+    "link": "/guide/start/introduction",
+    "activeMatch": "/guide/"
+  },
+  {
+    "text": "API",
+    "link": "/api/",
+    "activeMatch": "/api/"
+  },
+  {
+    "text": "Document",
+    "link": "https://rspress.rs/"
+  }
+]

package/template-basic/docs/api/_meta.json

@@ -0,0 +1 @@
+["index", "commands"]

package/template-basic/docs/api/commands.mdx

@@ -0,0 +1,7 @@
+# Commands
+
+## dev
+
+## build
+
+## preview

package/template-basic/docs/api/index.mdx

@@ -0,0 +1,6 @@
+---
+title: API Overview
+overview: true
+---
+
+This is an API Overview page which outlines all the available APIs.

package/template-basic/docs/guide/_meta.json

@@ -0,0 +1,12 @@
+[
+  {
+    "type": "dir-section-header",
+    "name": "start",
+    "label": "Getting Started"
+  },
+  {
+    "type": "dir-section-header",
+    "name": "use-mdx",
+    "label": "Markdown & MDX"
+  }
+]

package/template-basic/docs/guide/start/_meta.json

@@ -0,0 +1 @@
+["introduction", "getting-started"]

package/template-basic/docs/guide/start/getting-started.md

@@ -0,0 +1,51 @@
+# Getting started
+
+## Project structure
+
+After creating a project with `create-rspress`, you will get the following project structure:
+
+- `docs/` — The documentation source directory, configured via `root` in `rspress.config.ts`.
+- `docs/_nav.json` — The navigation bar configuration.
+- `docs/guide/_meta.json` — The sidebar configuration for the guide section.
+- `docs/public/` — Static assets directory.
+- `theme/` — Optional custom theme directory, generated when you choose the custom theme scaffold.
+- `rspress.config.ts` — The Rspress configuration file.
+
+## Development
+
+Start the local development server:
+
+```bash
+npm run dev
+```
+
+:::tip
+
+You can specify the port number or host with `--port` or `--host`, such as `rspress dev --port 8080 --host 0.0.0.0`.
+
+:::
+
+## Production build
+
+Build the site for production:
+
+```bash
+npm run build
+```
+
+By default, Rspress will output to `doc_build` directory.
+
+## Preview
+
+Preview the production build locally:
+
+```bash
+npm run preview
+```
+
+## Next steps
+
+- Learn how to use [MDX & React Components](/guide/use-mdx/components) in your docs.
+- Learn about [Code Blocks](/guide/use-mdx/code-blocks/) syntax highlighting and line highlighting.
+- Learn about [Custom Containers](/guide/use-mdx/container) for tips, warnings, and more.
+- Explore the full [Rspress documentation](https://rspress.rs/) for advanced features.

package/template-basic/docs/guide/start/introduction.md

@@ -0,0 +1,15 @@
+# Introduction
+
+Rspress is a static site generator based on [Rsbuild](https://rsbuild.rs/), rendered with the React framework. It comes with a default documentation theme, and you can quickly build a documentation site with Rspress.
+
+## Why Rspress
+
+- **Build Performance**. The core compilation module is based on the Rust front-end toolchain, providing millisecond-level startup and a more ultimate development experience.
+- **AI-native**. Technical documentation not only serves human readers but can also be better understood and utilized by AI through SSG-MD.
+- **MDX Support**. MDX is a powerful way to write content, allowing you to use React components in Markdown.
+- **Basic Capabilities**. Including full-text search, internationalization, multi-version support, component library documentation, etc.
+- **Extensibility**. Provides a built-in plugin system, supports extending Rspress through plugin API.
+
+## Try Rspress
+
+Go to [Getting Started](/guide/start/getting-started) to learn how to use Rspress to build a documentation site.

package/template-basic/docs/guide/use-mdx/_meta.json

@@ -0,0 +1 @@
+["components", { "type": "dir", "name": "code-blocks" }, "container"]

package/template-basic/docs/guide/use-mdx/code-blocks/_meta.json

@@ -0,0 +1 @@
+["title", "meta"]

package/template-basic/docs/guide/use-mdx/code-blocks/index.mdx

@@ -0,0 +1,9 @@
+# Code blocks
+
+Rspress uses [Shiki](https://shiki.style) for syntax highlighting at compile time, which means better runtime performance.
+
+When using code blocks in multiple languages, the corresponding language is automatically detected at compile time, and the runtime bundle size does not increase. For supported programming languages, refer to the [Shiki supported languages list](https://shiki.style/languages).
+
+```js
+console.log('Hello World');
+```

package/template-basic/docs/guide/use-mdx/code-blocks/meta.md

@@ -0,0 +1,7 @@
+# Meta
+
+Besides the title, we also have some other meta attributes.
+
+```ts lineNumbers wrapCode title="example.ts"
+const longLine = 'This code block has line numbers, code wrapping, and a title';
+```

package/template-basic/docs/guide/use-mdx/code-blocks/title.md

@@ -0,0 +1,5 @@
+# Title
+
+```js title="foo.js"
+console.log('Hello World');
+```

package/template-basic/docs/guide/use-mdx/components.mdx

@@ -0,0 +1,47 @@
+# MDX & React components
+
+Rspress supports not only Markdown but also [MDX](https://mdxjs.com/), a powerful way to develop content.
+
+## Markdown
+
+MDX is a superset of Markdown, which means you can write Markdown files as usual. For example:
+
+```md
+# Hello world
+```
+
+## Use components
+
+When you want to use React components in Markdown files, you should name your files with `.mdx` extension.
+
+```mdx
+// docs/index.mdx
+import { CustomComponent } from './custom';
+
+# Hello world
+
+<CustomComponent />
+```
+
+## Use Rspress built-in components
+
+import { Tabs, Tab } from '@rspress/core/theme';
+
+<Tabs>
+
+<Tab label="foo.js">
+
+```js
+console.log('foo');
+```
+
+</Tab>
+<Tab label="bar.js">
+
+```js
+console.log('bar');
+```
+
+</Tab>
+
+</Tabs>

package/template-basic/docs/guide/use-mdx/container.md

@@ -0,0 +1,33 @@
+# Container
+
+You can use the `:::` syntax to create custom containers and support custom titles.
+
+## Examples
+
+:::tip
+This is a `block` of type `tip`
+:::
+
+:::info
+This is a `block` of type `info`
+:::
+
+:::warning
+This is a `block` of type `warning`
+:::
+
+:::danger
+This is a `block` of type `danger`
+:::
+
+::: details
+This is a `block` of type `details`
+:::
+
+:::tip Custom Title
+This is a `block` of `Custom Title`
+:::
+
+:::tip{title="Custom Title"}
+This is a `block` of `Custom Title`
+:::

package/template-basic/docs/index.md

@@ -0,0 +1,43 @@
+---
+pageType: home
+
+hero:
+  name: My Site
+  text: A cool website!
+  tagline: This is the tagline
+  actions:
+    - theme: brand
+      text: Quick Start
+      link: /guide/start/introduction
+    - theme: alt
+      text: GitHub
+      link: https://github.com/web-infra-dev/rspress
+  image:
+    src: /rspress-icon.png
+    alt: Logo
+features:
+  - title: Blazing fast build speed
+    details: The core compilation module is based on the Rust front-end toolchain, providing a more ultimate development experience.
+    icon: 🏃🏻‍♀️
+    link: /guide/start/introduction
+  - title: Support for MDX content writing
+    details: MDX is a powerful way to write content, allowing you to use React components in Markdown.
+    icon: 📦
+    link: /guide/use-mdx/components
+  - title: Built-in full-text search
+    details: Automatically generates a full-text search index for you during construction, providing out-of-the-box full-text search capabilities.
+    icon: 🎨
+    link: https://rspress.rs/guide/advanced/custom-search
+  - title: AI-friendly
+    details: Generate llms.txt and Markdown files compliant with the llms.txt specification through SSG-MD, making it easier for large language models to understand and use your documentation.
+    icon: 🤖
+    link: https://rspress.rs/guide/basic/ssg-md
+  - title: Static site generation
+    details: In production, it automatically builds into static HTML files, which can be easily deployed anywhere.
+    icon: 🌈
+    link: https://rspress.rs/guide/basic/ssg
+  - title: Providing multiple custom capabilities
+    details: Through its extension mechanism, you can easily extend theme UI and build process.
+    icon: 🔥
+    link: https://rspress.rs/guide/basic/custom-theme
+---

package/template-basic-theme/theme/index.css

@@ -0,0 +1,12 @@
+/* Example brand color overrides for the custom theme scaffold. */
+/* For more CSS variables, see https://rspress.rs/ui/vars. */
+:root {
+  --rp-c-brand: #ff5e00;
+  --rp-c-brand-dark: #ff704d;
+  --rp-c-brand-darker: #ff704d;
+  --rp-c-brand-light: #ff7524;
+  --rp-c-brand-lighter: #ff7524;
+  --rp-c-brand-tint: rgba(255, 94, 0, 0.07);
+
+  --rp-home-hero-secondary-color: #ff5e00;
+}

package/template-basic-theme/theme/index.tsx

@@ -0,0 +1,4 @@
+// Learn how to customize the theme: https://rspress.rs/guide/basic/custom-theme
+import './index.css';
+
+export * from '@rspress/core/theme-original';

package/template-common/package.json

@@ -9,11 +9,11 @@
     "preview": "rspress preview"
   },
   "dependencies": {
-    "@rspress/core": "^2.0.11"
+    "@rspress/core": "^2.0.13"
   },
   "devDependencies": {
     "@types/node": "^22.8.1",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.6",
     "react-dom": "^19.2.6"

package/template-common/rspress.config.ts

@@ -3,6 +3,7 @@ import { defineConfig } from '@rspress/core';
 
 export default defineConfig({
   root: path.join(__dirname, 'docs'),
+  lang: 'en',
   title: 'My Site',
   icon: '/rspress-icon.png',
   logo: {

package/template-i18n/docs/en/_nav.json

@@ -0,0 +1,16 @@
+[
+  {
+    "text": "Guide",
+    "link": "/guide/start/introduction",
+    "activeMatch": "/guide/"
+  },
+  {
+    "text": "API",
+    "link": "/api/",
+    "activeMatch": "/api/"
+  },
+  {
+    "text": "Document",
+    "link": "https://rspress.rs/"
+  }
+]

package/template-i18n/docs/en/api/_meta.json

@@ -0,0 +1 @@
+["index", "commands"]

package/template-i18n/docs/en/api/commands.mdx

@@ -0,0 +1,11 @@
+---
+description: Command reference for Rspress development, production build, and local preview scripts.
+---
+
+# Commands
+
+## dev
+
+## build
+
+## preview

package/template-i18n/docs/en/api/index.mdx

@@ -0,0 +1,7 @@
+---
+title: API Overview
+description: Overview page for the Rspress starter API section and available reference pages.
+overview: true
+---
+
+This is an API Overview page which outlines all the available APIs.

package/template-i18n/docs/en/guide/_meta.json

@@ -0,0 +1,12 @@
+[
+  {
+    "type": "dir-section-header",
+    "name": "start",
+    "label": "Getting Started"
+  },
+  {
+    "type": "dir-section-header",
+    "name": "use-mdx",
+    "label": "Markdown & MDX"
+  }
+]

package/template-i18n/docs/en/guide/start/_meta.json

@@ -0,0 +1 @@
+["introduction", "getting-started"]

package/template-i18n/docs/en/guide/start/getting-started.md

@@ -0,0 +1,55 @@
+---
+description: Set up an Rspress project, run local development, build production output, and choose next docs topics.
+---
+
+# Getting started
+
+## Project structure
+
+After creating a project with `create-rspress`, you will get the following project structure:
+
+- `docs/` — The documentation source directory, configured via `root` in `rspress.config.ts`.
+- `docs/_nav.json` — The navigation bar configuration.
+- `docs/guide/_meta.json` — The sidebar configuration for the guide section.
+- `docs/public/` — Static assets directory.
+- `theme/` — Optional custom theme directory, generated when you choose the custom theme scaffold.
+- `rspress.config.ts` — The Rspress configuration file.
+
+## Development
+
+Start the local development server:
+
+```bash
+npm run dev
+```
+
+:::tip
+
+You can specify the port number or host with `--port` or `--host`, such as `rspress dev --port 8080 --host 0.0.0.0`.
+
+:::
+
+## Production build
+
+Build the site for production:
+
+```bash
+npm run build
+```
+
+By default, Rspress will output to `doc_build` directory.
+
+## Preview
+
+Preview the production build locally:
+
+```bash
+npm run preview
+```
+
+## Next steps
+
+- Learn how to use [MDX & React Components](/guide/use-mdx/components) in your docs.
+- Learn about [Code Blocks](/guide/use-mdx/code-blocks/) syntax highlighting and line highlighting.
+- Learn about [Custom Containers](/guide/use-mdx/container) for tips, warnings, and more.
+- Explore the full [Rspress documentation](https://rspress.rs/) for advanced features.

package/template-i18n/docs/en/guide/start/introduction.md

@@ -0,0 +1,19 @@
+---
+description: Introduction to Rspress features, including build performance, AI-native output, MDX, and extensibility.
+---
+
+# Introduction
+
+Rspress is a static site generator based on [Rsbuild](https://rsbuild.rs/), rendered with the React framework. It comes with a default documentation theme, and you can quickly build a documentation site with Rspress.
+
+## Why Rspress
+
+- **Build Performance**. The core compilation module is based on the Rust front-end toolchain, providing millisecond-level startup and a more ultimate development experience.
+- **AI-native**. Technical documentation not only serves human readers but can also be better understood and utilized by AI through SSG-MD.
+- **MDX Support**. MDX is a powerful way to write content, allowing you to use React components in Markdown.
+- **Basic Capabilities**. Including full-text search, internationalization, multi-version support, component library documentation, etc.
+- **Extensibility**. Provides a built-in plugin system, supports extending Rspress through plugin API.
+
+## Try Rspress
+
+Go to [Getting Started](/guide/start/getting-started) to learn how to use Rspress to build a documentation site.

package/template-i18n/docs/en/guide/use-mdx/_meta.json

@@ -0,0 +1 @@
+["components", { "type": "dir", "name": "code-blocks" }, "container"]

package/template-i18n/docs/en/guide/use-mdx/code-blocks/_meta.json

@@ -0,0 +1 @@
+["title", "meta"]

package/template-i18n/docs/en/guide/use-mdx/code-blocks/index.mdx

@@ -0,0 +1,13 @@
+---
+description: Configure Rspress code blocks with Shiki syntax highlighting and automatic language handling.
+---
+
+# Code blocks
+
+Rspress uses [Shiki](https://shiki.style) for syntax highlighting at compile time, which means better runtime performance.
+
+When using code blocks in multiple languages, the corresponding language is automatically detected at compile time, and the runtime bundle size does not increase. For supported programming languages, refer to the [Shiki supported languages list](https://shiki.style/languages).
+
+```js
+console.log('Hello World');
+```

package/template-i18n/docs/en/guide/use-mdx/code-blocks/meta.md

@@ -0,0 +1,11 @@
+---
+description: Add metadata such as line numbers, wrapping, and titles to Rspress code blocks.
+---
+
+# Meta
+
+Besides the title, we also have some other meta attributes.
+
+```ts lineNumbers wrapCode title="example.ts"
+const longLine = 'This code block has line numbers, code wrapping, and a title';
+```

package/template-i18n/docs/en/guide/use-mdx/code-blocks/title.md

@@ -0,0 +1,9 @@
+---
+description: Add file titles to Rspress code blocks using Markdown code fence metadata.
+---
+
+# Title
+
+```js title="foo.js"
+console.log('Hello World');
+```