文档系统快速上手

一、首先安装开发工具

1. 安装vscode： vscode 地址

2. 安装git： git 地址

3. 安装node.js：nodejs 地址

4. 安装插件Astro：Astro install 地址

5. 安装插件MDX：MDX install 地址

6. 安装插件Modern MDX Preview：MDX preview 地址

二、然后拉取代码库

1. 先在本地创建存放内部文档代码的文件夹，用于拉取代码库
   

2. 拉取内部文档git库代码：git clone https://codeup.aliyun.com/631fd8f7f9861067e4e846a7/docs-internal.git 鼠标右击创建的文件夹，选择Open Git Bash here打开方式 ，然后输入git clone命令。

   

   

3. 代码拉取好后，用vscode编程工具打开内部文档文件夹，即可进入开发阶段

   

   

   

三、最后编写文档

1. 创作内容

   • astro.sidebar.ts 侧边栏菜单配置
   • 文件夹src

     • 文件夹content

       • 文件夹docs 文档内容

         • en 英文文档所在文件夹
         • 文件夹cn 中文文档所在文件夹

           • 文件夹common 行业通用

             • index.mdx 首页/概览
             • 文件夹group1 分组 1

               • doc1.mdx
               • doc2.mdx
               • …
             • 文件夹group2 分组 2

               • doc1.mdx
               • doc2.mdx
               • …
           • 文件夹construction 建筑行业

             • index.mdx
             • …
           • 文件夹manufacturing 制造行业

             • index.mdx
             • …
           • 文件夹infrastructure 数智基建

             • index.mdx
             • …
       • 文件夹nav 菜单翻译词组

         • cn.ts 菜单中文翻译
         • en.ts 菜单英文翻译

2. 添加 页面

   直接在对应文件夹中创建文件

3. 添加 分组

   1. 在对应文件夹下创建文件夹

   2. 在 astro.sidebar.ts 中添加配置：

      astro.sidebar.ts

      export const sidebar = [
       group('construction', {
         items: [
           'construction',
           group('construction.project', {
             autogenerate: { directory: 'construction/project' },
             // or items
           }),
         ]
       }),
       group('manufacturing', {
         items: [
           'manufacturing',
           group('manufacturing.project', {
             autogenerate: { directory: 'manufacturing/project' }
           }),
         ]
       }),
      ] satisfies StarlightUserConfig['sidebar'];

      提示

      可前往 starlight菜单 详细了解菜单配置

   3. 在 src/content/nav/cn.ts & en.ts 中添加 中文 & 英文 翻译词组

4. 安装依赖：

   npm

   npm i

   pnpm

   pnpm i

   yarn

   yarn

5. 启动项目

   npm

   npm run dev

   pnpm

   pnpm dev

   yarn

   yarn dev

6. 浏览器访问： http://localhost:4321/zh-cn/

四、常用Frontmatter

xxx.mdx

  ---
  title: 文档标题
  # 建议填写，将被搜索引擎和社交媒体预览捕获
  description: 简介。
  # 从生产版本中排除此页面
  draft: true
  ---

五、国际化

VSCode 插件：starlight-i18n 帮助翻译 Starlight 页面的 Visual Studio Code 扩展。
基于git，比对不同语言的文件夹目录内容，给出还未翻译的文件列表。
注意：新文件须提交到git后，才能被识别。

六、使用图标

文档系统已经集成了astro-icon组件，支持Phosphor Icons图标库，使用方法如下：

import { Icon } from 'astro-icon/components';

<Icon name="ph:crown-duotone" class="w-9 h-9" />
<Icon name="ph:cow" class="w-9 h-9" />

ph图标库名称，在iconify网站查找，点击图标后在下方属性栏可以看到图标名称（name），即可在文档中使用。

七、转换成PDF

• 转换单个页面

  建议使用浏览器自带功能：Ctrl + P

• 转换整个解决方案

  行业通用

  npx starlight-to-pdf -u http://localhost:4321/cn/common/

  建筑行业

  npx starlight-to-pdf -u http://localhost:4321/cn/construction/

  制造行业

  npx starlight-to-pdf -u http://localhost:4321/cn/manufacturing/

  数智基建

  npx starlight-to-pdf -u http://localhost:4321/cn/infrastructure/

八、VSCode开发过程常用语法推荐

MDX MDX学习指南

starlight starlight学习指南

MarkDown MarkDown常用语法

git git常用命令