{"id":20082662,"url":"https://github.com/lexmin0412/rspress-template","last_synced_at":"2025-07-13T01:37:35.282Z","repository":{"id":201244255,"uuid":"707263158","full_name":"lexmin0412/rspress-template","owner":"lexmin0412","description":"基于 Rspress 构建、开箱即用的文档站点模板，集成 Github Actions 自动化部署、国际化等功能。","archived":false,"fork":false,"pushed_at":"2025-07-01T14:28:49.000Z","size":1255,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-13T01:37:33.581Z","etag":null,"topics":["blog","docs","rspress","website"],"latest_commit_sha":null,"homepage":"https://lexmin0412.github.io/rspress-template/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lexmin0412.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-19T14:40:51.000Z","updated_at":"2025-07-01T14:28:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"4f8b8d49-1aa6-49aa-bbff-f7da34285907","html_url":"https://github.com/lexmin0412/rspress-template","commit_stats":null,"previous_names":["lexmin0412/rspress-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/lexmin0412/rspress-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexmin0412%2Frspress-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexmin0412%2Frspress-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexmin0412%2Frspress-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexmin0412%2Frspress-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lexmin0412","download_url":"https://codeload.github.com/lexmin0412/rspress-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexmin0412%2Frspress-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265080033,"owners_count":23708102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog","docs","rspress","website"],"created_at":"2024-11-13T15:44:26.528Z","updated_at":"2025-07-13T01:37:35.221Z","avatar_url":"https://github.com/lexmin0412.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rspress Template\n\n基于 Rspress 构建、开箱即用的文档站点模板，集成 Github Actions 自动化部署、国际化等功能。\n\n## 模板搭建步骤\n\n### 1. 初始化模板\n\n通过 Rspress 脚手架命令创建项目：\n\n```shell\nnpm create rspress@latest\n```\n\n按照提示输入项目名称及描述等信息，即可创建一个 Rspress 项目。\n\n然后进入项目目录，安装依赖：\n\n```shell\n# 进入项目目录\ncd rspress-template\n# 安装依赖\npnpm install\n```\n\n### 2. 新建 README 文件\n\n在根目录新建 README.md 文件，填写基础信息：\n\n```markdown\n# Rspress Template\n\n基于 Rspress 构建的文档站点模板，集成了常用功能以达到开箱即用。\n```\n\n### 3. 本地开发及构建\n\n初始化模板后，Rspress 脚手架已经在 scripts 中注入了三个命令，分别是：\n\n- dev 启动本地开发服务器\n- build 生产环境构建\n- preview 本地预览 build 命令构建出的产物\n\n在终端运行以上命令，与预期结果一致，进入下一步。\n\n### 4. 第一次提交\n\n```shell\n# 初始化 Git 工作区\ngit init\n# 添加远程源\ngit remote add origin git@github.com:lexmin0412/rspress-template.git\n# 设置当前工作区的 git 账号，防止使用错误账号进行提交\ngcm use github\n# 暂存\ngit add .\n# 提交\ngit commit -m 'feat: 初始化模板'\n# 推送\ngit push -u origin main\n```\n\n### 5. 配置 Github Actions 实现自动化部署\n\n前置条件：github 仓库必须为 public，如果是 private，请先切换后再进行下面的步骤。\n\n#### 5.1 修改 GitHub Pages 部署方式\n\n当前版本的 Github Pages 默认部署方式为根据分支部署，我们需要切换到 Github Actions。\n\n![Github Pages 设置](./readme_assets/images/github_pages.jpg)\n\n#### 5.2 添加配置文件\n\n在根目录新建 .github/workflows/deploy.yml 文件，填入如下内容：\n\n```shell\nname: Deploy Rspress site to Pages\n\non:\n  push:\n    branches: [main]\n\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: pages\n  cancel-in-progress: false\n\njobs:\n  # Build job\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n        with:\n          fetch-depth: 0 # Not needed if lastUpdated is not enabled\n      - uses: pnpm/action-setup@v2 # pnpm is optional but recommended, you can also use npm / yarn\n        with:\n          version: 7\n          cache: pnpm\n      - name: Setup Node\n        uses: actions/setup-node@v3\n        with:\n          node-version: 18\n          cache: pnpm\n      - name: Setup Pages\n        uses: actions/configure-pages@v3\n      - name: Install dependencies\n        run: pnpm install\n      - name: Build with Rspress\n        run: |\n          pnpm run build\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v2\n        with:\n          path: doc_build\n\n  # Deployment job\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    needs: build\n    runs-on: ubuntu-latest\n    name: Deploy\n    steps:\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v2\n```\n\n#### 5.3 修改 rspress 配置\n\n由于我们的部署环境是 Github Pages，而它分配给每个 Repo 的只是一个域名下的二级路由，如仓库名为 rspress-template，则可访问的 pages 域名为 `https://lexmin0412.github.io/rspress-template`，所以我们需要调整 rspress 配置，以能够访问到部署目录下的静态资源文件(如 css/js 等)以及路由。\n\n修改根目录下的 rspress.config.ts, 加入如下内容：\n\n```ts\nexport default defineConfig({\n\t// history 路由前缀\n\tbase: '/rspress-template/',\n\tbuilderConfig: {\n\t\toutput: {\n\t\t\t// 给所有 static 目录下的静态文件引用添加前缀以便能够正确访问\n\t\t\tassetPrefix: '/rspress-template/'\n\t\t}\n\t},\n})\n```\n\n推送代码，等待 Actions 执行完成后访问 https://lexmin0412.github.io/rspress-template 查看效果。\n\n#### 5.4 修复图片\n\n在上面的步骤中，我们已经成功地部署了静态站点，但会发现 logo 图片依然无法访问。\n\n在 Rspress 构建后，docs/public 目录下的图片会被原封不动地移动到构建产物根目录下，所以我们修改 rspress.config.ts 文件：\n\n```ts\nexport default defineConfig({\n\ticon: \"https://lexmin0412.github.io/rspress-template/rspress-icon.png\",\n\tlogo: {\n\t\tlight: \"https://lexmin0412.github.io/rspress-template/rspress-light-logo.png\",\n\t\tdark: \"https://lexmin0412.github.io/rspress-template/rspress-dark-logo.png\",\n  },\n\tbuilderConfig: {\n\t\toutput: {\n\t\t\tassetPrefix: 'https://lexmin0412.github.io/rspress-template/'\n\t\t}\n\t},\n})\n```\n\n修改 docs/index.md，给图片加上路由前缀或改为完整的远程路径:\n\n```markdown\n---\npageType: home\n\nhero:\n  image:\n    src: /rspress-template/rspress-icon.png\n```\n\n再次推送代码，actions 执行成功后，会发现所有的 css/js/图片都加上了 assetPrefix 对应的值，可以正常访问了。\n\n### 6. 审视并调整目录结构\n\n初始化的目录结构如下：\n\n- guide 文档文件夹\n\t- meta.json\n\t- index.md\n- public\n\t- rspress-dark-logo.png\n\t- rspress-icon.png\n\t- rspress-light-logo.png\n- _meta.json 顶部导航栏\n- hello.md\n- index.md\n\n通过下图来看一下页面的基本结构：\n\n![页面布局](./readme_assets/images/site_layout.jpg)\n\n基于页面基本结构，我们来对这些已存在的文件做一个大体的说明，\n\n#### 6.1 index.md\n\n根目录的 index.md 作为整个文档站点的入口页，一般是对此站点的内容做一个大体的介绍，让用户一眼就能了解这个站点关联的产品，以及它们具体的用途。\n\n#### 6.2 _meta.json\n\n_meta.json 是 rspress (相对于 vitepress/vuepress 等)独有的配置文件，用于配置导航栏和侧边栏的内容，相对于在 rspress.config.ts 中配置 themeConfig 的方式，是官方更推荐的方式。\n\n它可以分为两类：\n\n- 导航栏级别，位于根目录\n- 侧边栏级别，位于子目录\n\n导航栏配置示例：\n\n```json\n[\n  {\n    \"text\": \"Guide\", // 菜单名\n    \"link\": \"/guide/\",  // 点击菜单的跳转链接\n    \"activeMatch\": \"^/guide/\"  // 匹配到这些条件时菜单高亮\n  }\n]\n```\n\n#### 6.2 guide\n\nguide 意为指南，一般作为一个目录看待，里面包含产品的使用文档，如列出组件库中每一个组件的使用方法、示例及属性说明。\n\n当然此目录不是必须存在的，它可以没有，也可以是其他名字，不过我们的目标是搭建一个通用的模板，就以此作为一个比较通用的示例。\n\nguide/index.md 文件，与在根目录中放置一个 guide.md 本质上并无区别，但由于 guide 目录下还会有其他很多相关的内容，就以此作为整个目录的入口。\n\nguide/_meta.json 即上文提到的 侧边栏 级别的 _meta.json 配置文件。\n\n#### 6.3 调整目录结构\n\n调整我们的目录结构如下：\n\n```shell\ndocs # 文档根目录\n|- guide # 指南\n   |- start # 开始\n      |- _meta.json # start 菜单下的侧边栏配置\n      |- quick-start.md # 子文档\n      |- introduction.md # 子文档\n   |- usage # 用法\n      |- index.md # 单一文章目录\n   |- _meta.json # guide 菜单下的侧边栏配置\n|- _meta.json # 导航栏配置\n|- index.md # 首页\n```\n\n其中三个 _meta.json 内容如下：\n\n`_meta.json`，其中包含对导航栏的菜单配置：\n\n```json\n[\n  {\n    \"text\": \"guide\",\n    \"link\": \"/guide/start/introduction\",\n    \"activeMatch\": \"/guide/\"\n  }\n]\n```\n\n`guide/_meta.json`，其中包含对 guide 目录下的菜单配置：\n```json\n[\n  {\n    \"type\": \"dir\",\n    \"name\": \"start\",\n    \"label\": \"start\"\n  }\n]\n```\n\n`guide/start/_meta.json`，其中包含对 guide/start 目录下的菜单配置：\n\n```json\n[\n  {\n    \"type\": \"file\",\n    \"name\": \"introduction\",\n    \"label\": \"introduction\"\n  },\n\t{\n    \"type\": \"file\",\n    \"name\": \"quick-start\",\n    \"label\": \"quick-start\"\n  }\n]\n```\n\n至此我们的目录结构调整告一段落。\n\n### 7. 国际化\n\n国际化在开源项目中属于比较常见的功能，所以我们也将它囊括进模板。\n\n官方的国际化指引请 [点我查看](https://rspress.dev/zh/guide/default-theme/i18n.html)，在此我们针对此模板进行配置。\n\n#### 7.1 定义 I18n 文本数据\n\n在工作区的根目录新建 i18n.json 文件，填入如下内容：\n\n```json\n{\n  \"guide\": {\n    \"zh\": \"指南\",\n    \"en\": \"Guide\"\n  },\n\t\"start\": {\n\t\t\"zh\": \"开始\",\n\t\t\"en\": \"Start\"\n\t},\n\t\"introduction\": {\n\t\t\"zh\": \"介绍\",\n\t\t\"en\": \"Introduction\"\n\t},\n\t\"quick-start\": {\n\t\t\"zh\": \"快速开始\",\n\t\t\"en\": \"Quick Start\"\n\t}\n}\n```\n\n基本的定义规范是：\n\n- key 使用英文小写，与文件名保持一致\n- 中文不带空格\n- 英文使用大写字母开头，多个单词使用空格分隔\n\n可以看到我们目前定义了顶部导航和侧边栏菜单的中英文文本。\n\n为了能够在 MDX 自定义组件中提供类型提示，我们需要在 tsconfig.json 中写入如下配置：\n\n```json\n{\n  \"compilerOptions\": {\n    \"paths\": {\n      \"i18n\": [\"./i18n.json\"]\n    }\n  }\n}\n```\n\n#### 7.2 配置默认语言\n\n在 rspress.config.ts 新增如下内容：\n\n```ts\nimport { defineConfig } from 'rspress/config';\n\nexport default defineConfig({\n  lang: 'zh',\n});\n```\n\n我们设置中文作为默认语言，对于默认语言下的路由，Rspress 会去除掉语言前缀，如 `rspress-template/zh/guide/start/quick-start` 会变为 `rspress-template/guide/start/quick-start`。\n\n#### 7.3 配置 locales 数据\n\nRspress 允许在 rspress.config.ts 中的 locales 和 themeConfig.locales 中配置 locales 数据，其中后者的优先级会更高，我们直接使用后者：\n\n```ts\nexport default defineConfig({\n\tthemeConfig: {\n\t\tlocales: [\n\t\t\t{\n\t\t\t\tlang: 'en',\n\t\t\t\tlabel: 'English',\n\t\t\t\t// 可以定义更多系统属性\n\t\t\t},\n\t\t\t{\n\t\t\t\tlang: 'zh',\n\t\t\t\tlabel: '简体中文',\n\t\t\t\t// 可以定义更多系统属性\n\t\t\t},\n\t\t],\n\t}\n})\n```\n\n此配置决定了在顶部导航栏的语言切换下拉菜单中的展示内容。\n\n在对应的语言下，还可以定义主题中的其他支持多语言的属性，如大纲、上一页/下一页、最后更新时间等，[点此查看](https://rspress.dev/zh/api/config/config-theme.html#locales) 类型定义。\n\n\n#### 7.4 调整目录结构\n\n为了支持多语言，我们需要将不同语言下的文件存放在不同的目录中。\n\n1. 在 docs 目录下分别新建 zh、en 文件夹\n2. 将除 public 和 zh 目录之外的所有文件全部移动到 zh 目录\n3. 将 zh 目录下的所有文件复制一份到 en 目录\n\n新的目录结构如下：\n\n```shell\ndocs\n|- zh # 中文\n   |- guide\n      |- start\n         |- _meta.json\n         |- quick-start.md\n         |- introduction.md\n      |- usage\n         |- index.md\n      |- _meta.json\n   |- _meta.json\n   |- index.md\n|- public # 静态资源，如文档中引用的图片、视频等\n|- en # 英文\n   |- guide\n      |- start\n         |- _meta.json\n         |- quick-start.md\n         |- introduction.md\n      |- usage\n         |- index.md\n      |- _meta.json\n   |- _meta.json\n   |- index.md\n```\n\n#### 7.5 使用 I18n 文本数据\n\n在 [7.1](#71-定义-i18n-文本数据) 中我们定义了文本数据，现在我们来使用。\n\n导航栏配置，以 zh/_meta.json 为例：\n\n```json\n[\n  {\n    \"text\": \"guide\",\n    \"link\": \"/guide/start/introduction\",\n    \"activeMatch\": \"/guide/\"\n  }\n]\n```\n\n`text` 属性即为 i18n key。\n\n侧边栏配置，以 zh/guide/_meta.json 为例：\n\n```json\n[\n  {\n    \"type\": \"dir\",\n    \"name\": \"start\",\n    \"label\": \"start\"\n  }\n]\n```\n\n`label` 属性即为 i18n key。\n\n#### 7.6 查看效果\n\n重新启动项目，会发现顶部导航栏的语言切换中显示了 English 和 中文 两个选项，顶部和左侧的菜单名称均显示了中文，这与我们的配置预期一致。\n\n![i18n 效果预览.png](./readme_assets/images/i18n-preview.png)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flexmin0412%2Frspress-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flexmin0412%2Frspress-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flexmin0412%2Frspress-template/lists"}