-```
-
-## Custom Container
-
-You can use the `:::` syntax to create custom containers and support custom titles. For example:
-
-**Input:**
-
-```markdown
-:::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`
-:::
-```
-
-**Output:**
-
-:::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`
-:::
-
-## Code Block
-
-### Basic Usage
-
-You can use the \`\`\` syntax to create code blocks and support custom titles. For example:
-
-**Input:**
-
-````md
-```js
-console.log('Hello World');
-```
-
-```js title="hello.js"
-console.log('Hello World');
-```
-````
-
-**Output:**
-
-```js
-console.log('Hello World');
-```
-
-```js title="hello.js"
-console.log('Hello World');
-```
-
-### Show Line Numbers
-
-If you want to display line numbers, you can enable the `showLineNumbers` option in the config file:
-
-```ts title="rspress.config.ts"
-export default {
- // ...
- markdown: {
- showLineNumbers: true,
- },
-};
-```
-
-### Wrap Code
-
-If you want to wrap long code line by default, you can enable the `defaultWrapCode` option in the config file:
-
-```ts title="rspress.config.ts"
-export default {
- // ...
- markdown: {
- defaultWrapCode: true,
- },
-};
-```
-
-### Line Highlighting
-
-You can also apply line highlighting and code block title at the same time, for example:
-
-**Input:**
-
-````md
-```js title="hello.js" {1,3-5}
-console.log('Hello World');
-
-const a = 1;
-
-console.log(a);
-
-const b = 2;
-
-console.log(b);
-```
-````
-
-**Ouput:**
-
-```js title="hello.js" {1,3-5}
-console.log('Hello World');
-
-const a = 1;
-
-console.log(a);
-
-const b = 2;
-
-console.log(b);
-```
-
-## Rustify MDX compiler
-
-You can enable Rustify MDX compiler by following config:
diff --git a/rspress/basic/docs/guide/start/_meta.json b/rspress/basic/docs/guide/start/_meta.json
new file mode 100644
index 000000000..88181a30a
--- /dev/null
+++ b/rspress/basic/docs/guide/start/_meta.json
@@ -0,0 +1 @@
+["introduction", "getting-started"]
diff --git a/rspress/basic/docs/guide/start/getting-started.md b/rspress/basic/docs/guide/start/getting-started.md
new file mode 100644
index 000000000..0b7b8d0fe
--- /dev/null
+++ b/rspress/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.
diff --git a/rspress/basic/docs/guide/start/introduction.md b/rspress/basic/docs/guide/start/introduction.md
new file mode 100644
index 000000000..b2d4e3ec4
--- /dev/null
+++ b/rspress/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.
diff --git a/rspress/basic/docs/guide/use-mdx/_meta.json b/rspress/basic/docs/guide/use-mdx/_meta.json
new file mode 100644
index 000000000..c188254f1
--- /dev/null
+++ b/rspress/basic/docs/guide/use-mdx/_meta.json
@@ -0,0 +1 @@
+["components", { "type": "dir", "name": "code-blocks" }, "container"]
diff --git a/rspress/basic/docs/guide/use-mdx/code-blocks/_meta.json b/rspress/basic/docs/guide/use-mdx/code-blocks/_meta.json
new file mode 100644
index 000000000..0a9e1bc25
--- /dev/null
+++ b/rspress/basic/docs/guide/use-mdx/code-blocks/_meta.json
@@ -0,0 +1 @@
+["title", "meta"]
diff --git a/rspress/basic/docs/guide/use-mdx/code-blocks/index.mdx b/rspress/basic/docs/guide/use-mdx/code-blocks/index.mdx
new file mode 100644
index 000000000..c193115b8
--- /dev/null
+++ b/rspress/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');
+```
diff --git a/rspress/basic/docs/guide/use-mdx/code-blocks/meta.md b/rspress/basic/docs/guide/use-mdx/code-blocks/meta.md
new file mode 100644
index 000000000..16385f283
--- /dev/null
+++ b/rspress/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';
+```
diff --git a/rspress/basic/docs/guide/use-mdx/code-blocks/title.md b/rspress/basic/docs/guide/use-mdx/code-blocks/title.md
new file mode 100644
index 000000000..cc6c9349c
--- /dev/null
+++ b/rspress/basic/docs/guide/use-mdx/code-blocks/title.md
@@ -0,0 +1,5 @@
+# Title
+
+```js title="foo.js"
+console.log('Hello World');
+```
diff --git a/rspress/basic/docs/guide/use-mdx/components.mdx b/rspress/basic/docs/guide/use-mdx/components.mdx
new file mode 100644
index 000000000..5e6465661
--- /dev/null
+++ b/rspress/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
+
+
+```
+
+## Use Rspress built-in components
+
+import { Tabs, Tab } from '@rspress/core/theme';
+
+
+
+
+
+```js
+console.log('foo');
+```
+
+
+
+
+```js
+console.log('bar');
+```
+
+
+
+
diff --git a/rspress/basic/docs/guide/use-mdx/container.md b/rspress/basic/docs/guide/use-mdx/container.md
new file mode 100644
index 000000000..0b121f07b
--- /dev/null
+++ b/rspress/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`
+:::
diff --git a/rspress/basic/docs/hello.md b/rspress/basic/docs/hello.md
deleted file mode 100644
index d08771599..000000000
--- a/rspress/basic/docs/hello.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Hello World!
-
-## Start
-
-Write something to build your own docs! 🎁
diff --git a/rspress/basic/docs/index.md b/rspress/basic/docs/index.md
index e6500ed37..8c04d408d 100644
--- a/rspress/basic/docs/index.md
+++ b/rspress/basic/docs/index.md
@@ -2,36 +2,42 @@
pageType: home
hero:
- name: Rspress
- text: Rspack-based Static Site Generator
- tagline: Rspress tagline
+ name: My Site
+ text: A cool website!
+ tagline: This is the tagline
actions:
- theme: brand
text: Quick Start
- link: /guide/
+ link: /guide/start/introduction
- theme: alt
- text: Github
+ text: GitHub
link: https://github.com/web-infra-dev/rspress
image:
src: /rspress-icon.png
- alt: Rspress Logo
+ 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: 🎨
- - title: Simpler I18n solution
- details: With the built-in I18n solution, you can easily provide multi-language support for documents or components.
- 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
---
diff --git a/rspress/basic/package.json b/rspress/basic/package.json
index f60350d81..7509d6d1f 100644
--- a/rspress/basic/package.json
+++ b/rspress/basic/package.json
@@ -2,15 +2,20 @@
"name": "@rspress-example/basic",
"version": "1.0.0",
"private": true,
+ "type": "module",
"scripts": {
"build": "rspress build",
"dev": "rspress dev",
"preview": "rspress preview"
},
"dependencies": {
- "rspress": "^1.47.1"
+ "@rspress/core": "^2.0.9"
},
"devDependencies": {
- "@types/node": "^24.10.9"
+ "@types/node": "^22.8.1",
+ "@types/react": "^19.2.14",
+ "@types/react-dom": "^19.2.3",
+ "react": "^19.2.4",
+ "react-dom": "^19.2.4"
}
}
diff --git a/rspress/basic/rspress.config.ts b/rspress/basic/rspress.config.ts
index c18acabb4..124e06271 100644
--- a/rspress/basic/rspress.config.ts
+++ b/rspress/basic/rspress.config.ts
@@ -1,10 +1,9 @@
-import * as path from 'path';
-import { defineConfig } from 'rspress/config';
+import path from 'node:path';
+import { defineConfig } from '@rspress/core';
export default defineConfig({
root: path.join(__dirname, 'docs'),
- title: 'Rspress',
- description: 'Rspack-based Static Site Generator',
+ title: 'My Site',
icon: '/rspress-icon.png',
logo: {
light: '/rspress-light-logo.png',
@@ -12,7 +11,11 @@ export default defineConfig({
},
themeConfig: {
socialLinks: [
- { icon: 'github', mode: 'link', content: 'https://github.com/web-infra-dev/rspress' },
+ {
+ icon: 'github',
+ mode: 'link',
+ content: 'https://github.com/web-infra-dev/rspress',
+ },
],
},
});
diff --git a/rspress/basic/tsconfig.json b/rspress/basic/tsconfig.json
index fb91f14d0..d3b51dd2a 100644
--- a/rspress/basic/tsconfig.json
+++ b/rspress/basic/tsconfig.json
@@ -1,6 +1,28 @@
{
"compilerOptions": {
+ "lib": ["DOM", "ES2020"],
"jsx": "react-jsx",
- "esModuleInterop": true
+ "target": "ES2020",
+ "noEmit": true,
+ "skipLibCheck": true,
+ "useDefineForClassFields": true,
+
+ /* modules */
+ "module": "ESNext",
+ "moduleDetection": "force",
+ "moduleResolution": "bundler",
+ "verbatimModuleSyntax": true,
+ "resolveJsonModule": true,
+ "allowImportingTsExtensions": true,
+ "isolatedModules": true,
+
+ /* type checking */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true
+ },
+ "include": ["docs", "theme", "rspress.config.ts"],
+ "mdx": {
+ "checkMdx": true
}
}
diff --git a/rspress/custom-theme/.gitignore b/rspress/custom-theme/.gitignore
deleted file mode 100644
index 044373fb2..000000000
--- a/rspress/custom-theme/.gitignore
+++ /dev/null
@@ -1,25 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-node_modules
-dist
-dist-ssr
-*.local
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
-doc_build
diff --git a/rspress/custom-theme/README.md b/rspress/custom-theme/README.md
new file mode 100644
index 000000000..8a9c78ca4
--- /dev/null
+++ b/rspress/custom-theme/README.md
@@ -0,0 +1,29 @@
+# Rspress website
+
+## Setup
+
+Install the dependencies:
+
+```bash
+npm install
+```
+
+## Get started
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Build the website for production:
+
+```bash
+npm run build
+```
+
+Preview the production build locally:
+
+```bash
+npm run preview
+```
diff --git a/rspress/custom-theme/docs/_nav.json b/rspress/custom-theme/docs/_nav.json
new file mode 100644
index 000000000..44093ff4c
--- /dev/null
+++ b/rspress/custom-theme/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/"
+ }
+]
diff --git a/rspress/custom-theme/docs/api/_meta.json b/rspress/custom-theme/docs/api/_meta.json
new file mode 100644
index 000000000..f0ff0de6d
--- /dev/null
+++ b/rspress/custom-theme/docs/api/_meta.json
@@ -0,0 +1 @@
+["index", "commands"]
diff --git a/rspress/custom-theme/docs/api/commands.mdx b/rspress/custom-theme/docs/api/commands.mdx
new file mode 100644
index 000000000..8a8b53dd9
--- /dev/null
+++ b/rspress/custom-theme/docs/api/commands.mdx
@@ -0,0 +1,7 @@
+# Commands
+
+## dev
+
+## build
+
+## preview
diff --git a/rspress/custom-theme/docs/api/index.mdx b/rspress/custom-theme/docs/api/index.mdx
new file mode 100644
index 000000000..939b29565
--- /dev/null
+++ b/rspress/custom-theme/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.
diff --git a/rspress/custom-theme/docs/guide/_meta.json b/rspress/custom-theme/docs/guide/_meta.json
new file mode 100644
index 000000000..090820a48
--- /dev/null
+++ b/rspress/custom-theme/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"
+ }
+]
diff --git a/rspress/custom-theme/docs/guide/start/_meta.json b/rspress/custom-theme/docs/guide/start/_meta.json
new file mode 100644
index 000000000..88181a30a
--- /dev/null
+++ b/rspress/custom-theme/docs/guide/start/_meta.json
@@ -0,0 +1 @@
+["introduction", "getting-started"]
diff --git a/rspress/custom-theme/docs/guide/start/getting-started.md b/rspress/custom-theme/docs/guide/start/getting-started.md
new file mode 100644
index 000000000..0b7b8d0fe
--- /dev/null
+++ b/rspress/custom-theme/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.
diff --git a/rspress/custom-theme/docs/guide/start/introduction.md b/rspress/custom-theme/docs/guide/start/introduction.md
new file mode 100644
index 000000000..b2d4e3ec4
--- /dev/null
+++ b/rspress/custom-theme/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.
diff --git a/rspress/custom-theme/docs/guide/use-mdx/_meta.json b/rspress/custom-theme/docs/guide/use-mdx/_meta.json
new file mode 100644
index 000000000..c188254f1
--- /dev/null
+++ b/rspress/custom-theme/docs/guide/use-mdx/_meta.json
@@ -0,0 +1 @@
+["components", { "type": "dir", "name": "code-blocks" }, "container"]
diff --git a/rspress/custom-theme/docs/guide/use-mdx/code-blocks/_meta.json b/rspress/custom-theme/docs/guide/use-mdx/code-blocks/_meta.json
new file mode 100644
index 000000000..0a9e1bc25
--- /dev/null
+++ b/rspress/custom-theme/docs/guide/use-mdx/code-blocks/_meta.json
@@ -0,0 +1 @@
+["title", "meta"]
diff --git a/rspress/custom-theme/docs/guide/use-mdx/code-blocks/index.mdx b/rspress/custom-theme/docs/guide/use-mdx/code-blocks/index.mdx
new file mode 100644
index 000000000..c193115b8
--- /dev/null
+++ b/rspress/custom-theme/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');
+```
diff --git a/rspress/custom-theme/docs/guide/use-mdx/code-blocks/meta.md b/rspress/custom-theme/docs/guide/use-mdx/code-blocks/meta.md
new file mode 100644
index 000000000..16385f283
--- /dev/null
+++ b/rspress/custom-theme/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';
+```
diff --git a/rspress/custom-theme/docs/guide/use-mdx/code-blocks/title.md b/rspress/custom-theme/docs/guide/use-mdx/code-blocks/title.md
new file mode 100644
index 000000000..cc6c9349c
--- /dev/null
+++ b/rspress/custom-theme/docs/guide/use-mdx/code-blocks/title.md
@@ -0,0 +1,5 @@
+# Title
+
+```js title="foo.js"
+console.log('Hello World');
+```
diff --git a/rspress/custom-theme/docs/guide/use-mdx/components.mdx b/rspress/custom-theme/docs/guide/use-mdx/components.mdx
new file mode 100644
index 000000000..5e6465661
--- /dev/null
+++ b/rspress/custom-theme/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
+
+
+```
+
+## Use Rspress built-in components
+
+import { Tabs, Tab } from '@rspress/core/theme';
+
+
+
+
+
+```js
+console.log('foo');
+```
+
+
+
+
+```js
+console.log('bar');
+```
+
+
+
+
diff --git a/rspress/custom-theme/docs/guide/use-mdx/container.md b/rspress/custom-theme/docs/guide/use-mdx/container.md
new file mode 100644
index 000000000..0b121f07b
--- /dev/null
+++ b/rspress/custom-theme/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`
+:::
diff --git a/rspress/custom-theme/docs/hello.md b/rspress/custom-theme/docs/hello.md
deleted file mode 100644
index d08771599..000000000
--- a/rspress/custom-theme/docs/hello.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Hello World!
-
-## Start
-
-Write something to build your own docs! 🎁
diff --git a/rspress/custom-theme/docs/index.md b/rspress/custom-theme/docs/index.md
index 250b98610..8c04d408d 100644
--- a/rspress/custom-theme/docs/index.md
+++ b/rspress/custom-theme/docs/index.md
@@ -2,33 +2,42 @@
pageType: home
hero:
- name: Rspress
- text: Rspack-based Static Site Generator
- tagline: Rspress tagline
+ name: My Site
+ text: A cool website!
+ tagline: This is the tagline
actions:
- theme: brand
text: Quick Start
- link: /hello/
+ link: /guide/start/introduction
- theme: alt
- text: Github
+ 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: 🎨
- - title: Simpler I18n solution
- details: With the built-in I18n solution, you can easily provide multi-language support for documents or components.
- 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
---
diff --git a/rspress/custom-theme/docs/public/rspress-dark-logo.png b/rspress/custom-theme/docs/public/rspress-dark-logo.png
new file mode 100644
index 000000000..928bcc916
Binary files /dev/null and b/rspress/custom-theme/docs/public/rspress-dark-logo.png differ
diff --git a/rspress/custom-theme/docs/public/rspress-icon.png b/rspress/custom-theme/docs/public/rspress-icon.png
new file mode 100644
index 000000000..6be2af2f7
Binary files /dev/null and b/rspress/custom-theme/docs/public/rspress-icon.png differ
diff --git a/rspress/custom-theme/docs/public/rspress-light-logo.png b/rspress/custom-theme/docs/public/rspress-light-logo.png
new file mode 100644
index 000000000..1e3442eec
Binary files /dev/null and b/rspress/custom-theme/docs/public/rspress-light-logo.png differ
diff --git a/rspress/custom-theme/package.json b/rspress/custom-theme/package.json
index e26e05d77..c3294b2e2 100644
--- a/rspress/custom-theme/package.json
+++ b/rspress/custom-theme/package.json
@@ -2,17 +2,18 @@
"name": "@rspress-example/custom-theme",
"version": "1.0.0",
"private": true,
+ "type": "module",
"scripts": {
"build": "rspress build",
"dev": "rspress dev",
"preview": "rspress preview"
},
"dependencies": {
- "rspress": "^1.47.1"
+ "@rspress/core": "^2.0.9"
},
"devDependencies": {
- "@types/node": "^24.10.9",
- "@types/react": "^19.2.10",
+ "@types/node": "^22.8.1",
+ "@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
"react": "^19.2.4",
"react-dom": "^19.2.4"
diff --git a/rspress/custom-theme/rspress.config.ts b/rspress/custom-theme/rspress.config.ts
index 39cd2c068..124e06271 100644
--- a/rspress/custom-theme/rspress.config.ts
+++ b/rspress/custom-theme/rspress.config.ts
@@ -1,11 +1,21 @@
-import * as path from 'path';
-import { defineConfig } from 'rspress/config';
+import path from 'node:path';
+import { defineConfig } from '@rspress/core';
export default defineConfig({
root: path.join(__dirname, 'docs'),
+ title: 'My Site',
+ icon: '/rspress-icon.png',
+ logo: {
+ light: '/rspress-light-logo.png',
+ dark: '/rspress-dark-logo.png',
+ },
themeConfig: {
- footer: {
- createdBy: 'Rspress',
- } as any,
+ socialLinks: [
+ {
+ icon: 'github',
+ mode: 'link',
+ content: 'https://github.com/web-infra-dev/rspress',
+ },
+ ],
},
});
diff --git a/rspress/custom-theme/theme/env.d.ts b/rspress/custom-theme/theme/env.d.ts
new file mode 100644
index 000000000..66e7b5d0f
--- /dev/null
+++ b/rspress/custom-theme/theme/env.d.ts
@@ -0,0 +1,9 @@
+declare module '*.css';
+
+interface ImportMetaEnv {
+ readonly SSG_MD: boolean;
+}
+
+interface ImportMeta {
+ readonly env: ImportMetaEnv;
+}
diff --git a/rspress/custom-theme/theme/index.css b/rspress/custom-theme/theme/index.css
new file mode 100644
index 000000000..f737457a8
--- /dev/null
+++ b/rspress/custom-theme/theme/index.css
@@ -0,0 +1,6 @@
+:root {
+ /* Example brand color overrides for the custom theme scaffold. */
+ --rp-c-brand: #0f766e;
+ --rp-c-brand-dark: #115e59;
+ --rp-c-brand-tint: rgba(15, 118, 110, 0.16);
+}
diff --git a/rspress/custom-theme/theme/index.tsx b/rspress/custom-theme/theme/index.tsx
index 0acca6070..de35b1856 100644
--- a/rspress/custom-theme/theme/index.tsx
+++ b/rspress/custom-theme/theme/index.tsx
@@ -1,20 +1,3 @@
-import Theme from 'rspress/theme';
-import { usePageData } from 'rspress/runtime';
+import './index.css';
-// to replace home footer
-export function HomeFooter() {
- const { siteData } = usePageData();
- const { createdBy } = (siteData.themeConfig.footer || {}) as any;
- // use configuration from rspress.config
-
- return (
-
- );
-}
-
-export default Theme;
-export * from 'rspress/theme';
+export * from '@rspress/core/theme-original';
diff --git a/rspress/custom-theme/tsconfig.json b/rspress/custom-theme/tsconfig.json
index fb91f14d0..d3b51dd2a 100644
--- a/rspress/custom-theme/tsconfig.json
+++ b/rspress/custom-theme/tsconfig.json
@@ -1,6 +1,28 @@
{
"compilerOptions": {
+ "lib": ["DOM", "ES2020"],
"jsx": "react-jsx",
- "esModuleInterop": true
+ "target": "ES2020",
+ "noEmit": true,
+ "skipLibCheck": true,
+ "useDefineForClassFields": true,
+
+ /* modules */
+ "module": "ESNext",
+ "moduleDetection": "force",
+ "moduleResolution": "bundler",
+ "verbatimModuleSyntax": true,
+ "resolveJsonModule": true,
+ "allowImportingTsExtensions": true,
+ "isolatedModules": true,
+
+ /* type checking */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true
+ },
+ "include": ["docs", "theme", "rspress.config.ts"],
+ "mdx": {
+ "checkMdx": true
}
}