From a77bb5dccbaf6963b3e7faa87359712a0ba649eb Mon Sep 17 00:00:00 2001 From: neverland Date: Sat, 8 Aug 2026 21:19:06 +0800 Subject: [PATCH 1/2] feat(create-rstack): add basic documentation template --- packages/create-rstack/README.md | 1 + packages/create-rstack/src/index.ts | 11 +++++ .../template-doc-basic/AGENTS.md | 12 +++++ .../template-doc-basic/README.md | 34 ++++++++++++++ .../template-doc-basic/docs/_nav.json | 16 +++++++ .../template-doc-basic/docs/api/_meta.json | 1 + .../template-doc-basic/docs/api/commands.mdx | 25 ++++++++++ .../template-doc-basic/docs/api/index.mdx | 6 +++ .../template-doc-basic/docs/guide/_meta.json | 7 +++ .../docs/guide/start/_meta.json | 1 + .../docs/guide/start/getting-started.md | 46 +++++++++++++++++++ .../docs/guide/start/introduction.md | 15 ++++++ .../template-doc-basic/docs/index.md | 39 ++++++++++++++++ .../template-doc-basic/gitignore | 14 ++++++ .../template-doc-basic/package.json | 23 ++++++++++ .../template-doc-basic/rstack.config.ts | 19 ++++++++ .../template-doc-basic/tsconfig.json | 26 +++++++++++ packages/create-rstack/tests/create.test.ts | 18 ++++++++ 18 files changed, 314 insertions(+) create mode 100644 packages/create-rstack/template-doc-basic/AGENTS.md create mode 100644 packages/create-rstack/template-doc-basic/README.md create mode 100644 packages/create-rstack/template-doc-basic/docs/_nav.json create mode 100644 packages/create-rstack/template-doc-basic/docs/api/_meta.json create mode 100644 packages/create-rstack/template-doc-basic/docs/api/commands.mdx create mode 100644 packages/create-rstack/template-doc-basic/docs/api/index.mdx create mode 100644 packages/create-rstack/template-doc-basic/docs/guide/_meta.json create mode 100644 packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json create mode 100644 packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md create mode 100644 packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md create mode 100644 packages/create-rstack/template-doc-basic/docs/index.md create mode 100644 packages/create-rstack/template-doc-basic/gitignore create mode 100644 packages/create-rstack/template-doc-basic/package.json create mode 100644 packages/create-rstack/template-doc-basic/rstack.config.ts create mode 100644 packages/create-rstack/template-doc-basic/tsconfig.json diff --git a/packages/create-rstack/README.md b/packages/create-rstack/README.md index 11e33dde..9a453522 100644 --- a/packages/create-rstack/README.md +++ b/packages/create-rstack/README.md @@ -37,6 +37,7 @@ npx create-rstack -d my-project -t app-vanilla-ts - `lib-vue-ts` - TypeScript Vue library - `lib-solid-js` - JavaScript Solid library - `lib-solid-ts` - TypeScript Solid library +- `doc-basic` - Basic documentation site ## Documentation diff --git a/packages/create-rstack/src/index.ts b/packages/create-rstack/src/index.ts index 2aa269a5..428c6e41 100644 --- a/packages/create-rstack/src/index.ts +++ b/packages/create-rstack/src/index.ts @@ -23,6 +23,11 @@ const getTemplateName = async ({ template }: Argv): Promise => { return `lib-${libraryType}-${language}`; } + if (template === 'doc' || template.startsWith('doc-')) { + const [, documentationType = 'basic'] = template.split('-'); + return `doc-${documentationType}`; + } + const [type, language = 'js'] = template.split('-'); return `${type}-${language}`; } @@ -33,10 +38,15 @@ const getTemplateName = async ({ template }: Argv): Promise => { options: [ { value: 'app', label: 'Web Application' }, { value: 'lib', label: 'Library' }, + { value: 'doc', label: 'Documentation' }, ], }), ); + if (projectType === 'doc') { + return 'doc-basic'; + } + const templateType = checkCancel( await select({ message: projectType === 'app' ? 'Select framework' : 'Select library type', @@ -90,6 +100,7 @@ await create({ 'lib-vue-ts', 'lib-solid-js', 'lib-solid-ts', + 'doc-basic', ], builtinTools: [], getTemplateName, diff --git a/packages/create-rstack/template-doc-basic/AGENTS.md b/packages/create-rstack/template-doc-basic/AGENTS.md new file mode 100644 index 00000000..53041074 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/AGENTS.md @@ -0,0 +1,12 @@ +# AGENTS.md + +## Commands + +- `{{ packageManager }} run dev` - Start the documentation development server +- `{{ packageManager }} run build` - Build the documentation site for production +- `{{ packageManager }} run preview` - Preview the production build locally + +## Docs + +- Rspress: https://rspress.rs/llms.txt +- Rsbuild: https://rsbuild.rs/llms.txt diff --git a/packages/create-rstack/template-doc-basic/README.md b/packages/create-rstack/template-doc-basic/README.md new file mode 100644 index 00000000..513fc4a9 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/README.md @@ -0,0 +1,34 @@ +# Rstack documentation site + +## Setup + +Install the dependencies: + +```bash +{{ packageManager }} install +``` + +## Get started + +Start the development server: + +```bash +{{ packageManager }} run dev +``` + +Build the website for production: + +```bash +{{ packageManager }} run build +``` + +Preview the production build locally: + +```bash +{{ packageManager }} run preview +``` + +## Learn more + +- [Rstack documentation](https://rstack.rs) +- [Rspress documentation](https://rspress.rs) diff --git a/packages/create-rstack/template-doc-basic/docs/_nav.json b/packages/create-rstack/template-doc-basic/docs/_nav.json new file mode 100644 index 00000000..1c47924a --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/_nav.json @@ -0,0 +1,16 @@ +[ + { + "text": "Guide", + "link": "/guide/start/introduction", + "activeMatch": "/guide/" + }, + { + "text": "API", + "link": "/api/", + "activeMatch": "/api/" + }, + { + "text": "Rspress", + "link": "https://rspress.rs/" + } +] diff --git a/packages/create-rstack/template-doc-basic/docs/api/_meta.json b/packages/create-rstack/template-doc-basic/docs/api/_meta.json new file mode 100644 index 00000000..f0ff0de6 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/api/_meta.json @@ -0,0 +1 @@ +["index", "commands"] diff --git a/packages/create-rstack/template-doc-basic/docs/api/commands.mdx b/packages/create-rstack/template-doc-basic/docs/api/commands.mdx new file mode 100644 index 00000000..6e7494c5 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/api/commands.mdx @@ -0,0 +1,25 @@ +# Commands + +## dev + +Start the local development server: + +```bash +rs doc +``` + +## build + +Build the documentation site for production: + +```bash +rs doc build +``` + +## preview + +Preview the production build locally: + +```bash +rs doc preview +``` diff --git a/packages/create-rstack/template-doc-basic/docs/api/index.mdx b/packages/create-rstack/template-doc-basic/docs/api/index.mdx new file mode 100644 index 00000000..939b2956 --- /dev/null +++ b/packages/create-rstack/template-doc-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. diff --git a/packages/create-rstack/template-doc-basic/docs/guide/_meta.json b/packages/create-rstack/template-doc-basic/docs/guide/_meta.json new file mode 100644 index 00000000..2dc352c6 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/guide/_meta.json @@ -0,0 +1,7 @@ +[ + { + "type": "dir-section-header", + "name": "start", + "label": "Getting Started" + } +] diff --git a/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json b/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json new file mode 100644 index 00000000..88181a30 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json @@ -0,0 +1 @@ +["introduction", "getting-started"] diff --git a/packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md b/packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md new file mode 100644 index 00000000..578d1d6a --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md @@ -0,0 +1,46 @@ +# Getting started + +## Project structure + +After creating a documentation project with `create-rstack`, you will get the following project structure: + +- `docs/` — The documentation source directory, configured via `root` in `rstack.config.ts`. +- `docs/_nav.json` — The navigation bar configuration. +- `docs/guide/_meta.json` — The sidebar configuration for the guide section. +- `rstack.config.ts` — The Rstack configuration file, including the Rspress configuration registered with `define.doc()`. + +## Development + +Start the local development server: + +```bash +{{ packageManager }} run dev +``` + +:::tip + +You can specify the port number or host with `--port` or `--host`, such as `rs doc --port 8080 --host 0.0.0.0`. + +::: + +## Production build + +Build the site for production: + +```bash +{{ packageManager }} run build +``` + +By default, Rspress will output to the `doc_build` directory. + +## Preview + +Preview the production build locally: + +```bash +{{ packageManager }} run preview +``` + +## Next steps + +- Explore the full [Rspress documentation](https://rspress.rs/) for advanced features. diff --git a/packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md b/packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md new file mode 100644 index 00000000..b2d4e3ec --- /dev/null +++ b/packages/create-rstack/template-doc-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/packages/create-rstack/template-doc-basic/docs/index.md b/packages/create-rstack/template-doc-basic/docs/index.md new file mode 100644 index 00000000..d47c03f4 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/docs/index.md @@ -0,0 +1,39 @@ +--- +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/rstackjs/rstack-cli + image: + src: https://assets.rspack.rs/rspress/rspress-logo.svg + 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: 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 +--- diff --git a/packages/create-rstack/template-doc-basic/gitignore b/packages/create-rstack/template-doc-basic/gitignore new file mode 100644 index 00000000..23a4bc92 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/gitignore @@ -0,0 +1,14 @@ +# Local +.DS_Store +*.local +*.log* + +# Dist +node_modules +dist/ +doc_build/ + +# IDE +.vscode/* +!.vscode/extensions.json +.idea diff --git a/packages/create-rstack/template-doc-basic/package.json b/packages/create-rstack/template-doc-basic/package.json new file mode 100644 index 00000000..fa5f892a --- /dev/null +++ b/packages/create-rstack/template-doc-basic/package.json @@ -0,0 +1,23 @@ +{ + "name": "rstack-doc-basic", + "version": "0.0.0", + "private": true, + "type": "module", + "scripts": { + "build": "rs doc build", + "dev": "rs doc", + "format": "rs fmt", + "lint": "rs lint", + "preview": "rs doc preview" + }, + "devDependencies": { + "@rspress/core": "^2.0.19", + "@types/node": "^24.13.3", + "@types/react": "^19.2.18", + "@types/react-dom": "^19.2.4", + "react": "^19.2.8", + "react-dom": "^19.2.8", + "rstack": "^0.3.5", + "typescript": "^7.0.2" + } +} diff --git a/packages/create-rstack/template-doc-basic/rstack.config.ts b/packages/create-rstack/template-doc-basic/rstack.config.ts new file mode 100644 index 00000000..550d8823 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/rstack.config.ts @@ -0,0 +1,19 @@ +// Rstack configuration guide: https://rstack.rs/config +import path from 'node:path'; +import { define } from 'rstack'; + +define.doc({ + root: path.join(import.meta.dirname, 'docs'), + title: 'My Site', +}); + +define.lint(async () => { + const { js, ts, reactPlugin, reactHooksPlugin } = await import('rstack/lint'); + + return [ + js.configs.recommended, + ts.configs.recommended, + reactPlugin.configs.recommended, + reactHooksPlugin.configs.recommended, + ]; +}); diff --git a/packages/create-rstack/template-doc-basic/tsconfig.json b/packages/create-rstack/template-doc-basic/tsconfig.json new file mode 100644 index 00000000..559f2a04 --- /dev/null +++ b/packages/create-rstack/template-doc-basic/tsconfig.json @@ -0,0 +1,26 @@ +{ + "compilerOptions": { + "lib": ["DOM", "ES2020"], + "jsx": "react-jsx", + "target": "ES2020", + "noEmit": true, + "skipLibCheck": true, + "types": ["rstack/types", "node"], + "useDefineForClassFields": true, + + /* modules */ + "moduleDetection": "force", + "moduleResolution": "bundler", + "verbatimModuleSyntax": true, + "resolveJsonModule": true, + "allowImportingTsExtensions": true, + + /* type checking */ + "noUnusedLocals": true, + "noUnusedParameters": true + }, + "include": ["docs", "rstack.config.ts"], + "mdx": { + "checkMdx": true + } +} diff --git a/packages/create-rstack/tests/create.test.ts b/packages/create-rstack/tests/create.test.ts index 70936bf7..7258fe0c 100644 --- a/packages/create-rstack/tests/create.test.ts +++ b/packages/create-rstack/tests/create.test.ts @@ -118,6 +118,24 @@ test.each([ }, ); +test('creates the doc-basic template', async () => { + const projectDirectory = await createProject('doc-basic'); + const packageJson = JSON.parse( + await readFile(path.join(projectDirectory, 'package.json'), 'utf8'), + ); + + expect(packageJson.name).toBe('my-app'); + + await expect(access(path.join(projectDirectory, 'README.md'))).resolves.toBeUndefined(); + await expect(access(path.join(projectDirectory, '.gitignore'))).resolves.toBeUndefined(); + await expect(access(path.join(projectDirectory, 'rstack.config.ts'))).resolves.toBeUndefined(); + await expect(access(path.join(projectDirectory, 'tsconfig.json'))).resolves.toBeUndefined(); + await expect(access(path.join(projectDirectory, 'docs', 'index.md'))).resolves.toBeUndefined(); + await expect( + access(path.join(projectDirectory, 'docs', 'guide', 'start', 'getting-started.md')), + ).resolves.toBeUndefined(); +}); + test.each([ { template: 'lib-node-js', From 136a33f50ff7b36e71908d5583719d34e3368e7e Mon Sep 17 00:00:00 2001 From: neverland Date: Sat, 8 Aug 2026 21:23:56 +0800 Subject: [PATCH 2/2] refactor(create-rstack): simplify documentation template --- .../template-doc-basic/AGENTS.md | 1 + .../docs/guide/start/_meta.json | 2 +- .../docs/guide/start/getting-started.md | 46 ------------------- .../docs/guide/start/introduction.md | 14 +----- packages/create-rstack/tests/create.test.ts | 2 +- 5 files changed, 5 insertions(+), 60 deletions(-) delete mode 100644 packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md diff --git a/packages/create-rstack/template-doc-basic/AGENTS.md b/packages/create-rstack/template-doc-basic/AGENTS.md index 53041074..456cacda 100644 --- a/packages/create-rstack/template-doc-basic/AGENTS.md +++ b/packages/create-rstack/template-doc-basic/AGENTS.md @@ -8,5 +8,6 @@ ## Docs +- Rstack: https://rstack.rs/llms.txt - Rspress: https://rspress.rs/llms.txt - Rsbuild: https://rsbuild.rs/llms.txt diff --git a/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json b/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json index 88181a30..f818265c 100644 --- a/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json +++ b/packages/create-rstack/template-doc-basic/docs/guide/start/_meta.json @@ -1 +1 @@ -["introduction", "getting-started"] +["introduction"] diff --git a/packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md b/packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md deleted file mode 100644 index 578d1d6a..00000000 --- a/packages/create-rstack/template-doc-basic/docs/guide/start/getting-started.md +++ /dev/null @@ -1,46 +0,0 @@ -# Getting started - -## Project structure - -After creating a documentation project with `create-rstack`, you will get the following project structure: - -- `docs/` — The documentation source directory, configured via `root` in `rstack.config.ts`. -- `docs/_nav.json` — The navigation bar configuration. -- `docs/guide/_meta.json` — The sidebar configuration for the guide section. -- `rstack.config.ts` — The Rstack configuration file, including the Rspress configuration registered with `define.doc()`. - -## Development - -Start the local development server: - -```bash -{{ packageManager }} run dev -``` - -:::tip - -You can specify the port number or host with `--port` or `--host`, such as `rs doc --port 8080 --host 0.0.0.0`. - -::: - -## Production build - -Build the site for production: - -```bash -{{ packageManager }} run build -``` - -By default, Rspress will output to the `doc_build` directory. - -## Preview - -Preview the production build locally: - -```bash -{{ packageManager }} run preview -``` - -## Next steps - -- Explore the full [Rspress documentation](https://rspress.rs/) for advanced features. diff --git a/packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md b/packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md index b2d4e3ec..0bf0ab47 100644 --- a/packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md +++ b/packages/create-rstack/template-doc-basic/docs/guide/start/introduction.md @@ -1,15 +1,5 @@ # 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. +Rspress is a fast static site generator based on [Rsbuild](https://rsbuild.rs/). It supports Markdown and MDX and includes a default documentation theme. -## 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. +Learn more in the [Rspress documentation](https://rspress.rs/). diff --git a/packages/create-rstack/tests/create.test.ts b/packages/create-rstack/tests/create.test.ts index 7258fe0c..5e7bcda5 100644 --- a/packages/create-rstack/tests/create.test.ts +++ b/packages/create-rstack/tests/create.test.ts @@ -132,7 +132,7 @@ test('creates the doc-basic template', async () => { await expect(access(path.join(projectDirectory, 'tsconfig.json'))).resolves.toBeUndefined(); await expect(access(path.join(projectDirectory, 'docs', 'index.md'))).resolves.toBeUndefined(); await expect( - access(path.join(projectDirectory, 'docs', 'guide', 'start', 'getting-started.md')), + access(path.join(projectDirectory, 'docs', 'guide', 'start', 'introduction.md')), ).resolves.toBeUndefined(); });