create-rspress 2.0.4 → 2.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rspress",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Create a new Rspress project",
   "homepage": "https://rspress.rs",
   "repository": {
@@ -26,8 +26,8 @@
     "create-rstack": "1.8.0"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.57.6",
-    "@rslib/core": "0.19.6",
+    "@microsoft/api-extractor": "^7.57.7",
+    "@rslib/core": "0.20.0",
     "@types/node": "^22.8.1",
     "rsbuild-plugin-publint": "^0.3.4",
     "typescript": "^5.8.2"

package/template-basic/docs/_nav.json

@@ -1,16 +1,16 @@
 [
   {
     "text": "Guide",
-    "link": "/guide/",
+    "link": "/guide/start/introduction",
     "activeMatch": "/guide/"
   },
   {
-    "text": "Hello world",
-    "link": "/hello/",
-    "activeMatch": "/hello/"
+    "text": "API",
+    "link": "/api/",
+    "activeMatch": "/api/"
   },
   {
-    "text": "API",
-    "link": "https://rspress.rs/api/index.html"
+    "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

@@ -1 +1,12 @@
-["index"]
+[
+  {
+    "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,50 @@
+# 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.
+- `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

@@ -8,7 +8,7 @@ hero:
   actions:
     - theme: brand
       text: Quick Start
-      link: /guide/
+      link: /guide/start/introduction
     - theme: alt
       text: GitHub
       link: https://github.com/web-infra-dev/rspress
@@ -19,19 +19,25 @@ 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
 ---

package/template-basic/docs/guide/index.md

@@ -1,216 +0,0 @@
-# Markdown & MDX
-
-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 component
-
-When you want to use React components in Markdown files, you should name your files with `.mdx` extension. For example:
-
-```mdx
-// docs/index.mdx
-import { CustomComponent } from './custom';
-
-# Hello world
-
-<CustomComponent />
-```
-
-## Front matter
-
-You can add Front Matter at the beginning of your Markdown file, which is a YAML-formatted object that defines some metadata. For example:
-
-```yaml
----
-title: Hello world
----
-```
-
-> Note: By default, Rspress uses h1 headings as html headings.
-
-You can also access properties defined in Front Matter in the body, for example:
-
-```markdown
----
-title: Hello world
----
-
-# {frontmatter.title}
-```
-
-The previously defined properties will be passed to the component as `frontmatter` properties. So the final output will be:
-
-```html
-<h1>Hello world</h1>
-```
-
-## 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"
-console.log('Hello World'); // [\!code highlight]
-
-// [\!code highlight:3]
-const a = 1;
-
-console.log(a);
-
-const b = 2;
-
-console.log(b);
-```
-````
-
-:::warning
-The backslash (`\`) in `[\!code highlight]` is for Markdown escaping to display the raw syntax. Do not include it when using this notation in your actual code.
-:::
-
-**Output:**
-
-```js title="hello.js"
-console.log('Hello World'); // [!code highlight]
-
-// [!code highlight:3]
-const a = 1;
-
-console.log(a);
-
-const b = 2;
-
-console.log(b);
-```
-
-## Rustify MDX compiler
-
-You can enable Rustify MDX compiler by following config:

package/template-basic/docs/hello.md

@@ -1,5 +0,0 @@
-# Hello world!
-
-## Start
-
-Write something to build your own docs! 🎁