在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

microsoft/Web-Dev-For-Beginners

菜单

文档系统

相关源文件

面向初学者的 Web 开发文档系统是一个框架，它将课程的 Markdown 内容渲染成一个可访问的多语言网站，同时还支持 PDF 生成。本文档将解释文档是如何实现、配置和维护的。有关翻译框架本身的更多信息，请参阅 翻译框架。

文档系统概述

面向初学者的 Web 开发课程使用 Docsify 作为其文档系统，以用户友好的格式呈现教学内容。Docsify 是一个轻量级的、由 Vue 驱动的文档生成器，它在客户端动态渲染 Markdown 文件为 HTML。这种方法消除了构建静态 HTML 文件的需要，从而实现了更简单的内容管理工作流。

该文档系统提供了几个关键功能：

  • Markdown 内容的动态渲染
  • 通过翻译支持多语言
  • 针对各种设备的响应式设计
  • PDF 生成能力
  • GitHub Pages 集成

来源：index.html1-43 package.json1-28

架构

文档系统架构

来源：index.html1-43 docs/_navbar.md1-21 docs/_sidebar.md1-37 index.css1-3 docsifytopdf.js1-10

文件结构和内容流

来源：index.html1-43 docs/_navbar.md1-21 docs/_sidebar.md1-37 index.css1-3 docsifytopdf.js1-10

Docsify配置

文档系统的核心配置在 index.html 文件中。该文件包含控制 Docsify 如何渲染内容和功能的设置。

关键配置参数

这些设置控制：

  • loadNavbar：指向提供语言选择的导航栏文件
  • name：设置文档的标题
  • repo：链接到 GitHub 存储库
  • relativePath：在导航中使用相对路径
  • alias：将 URL 模式映射到文件路径，支持翻译结构

别名模式对于处理多语言内容尤其重要，允许英语（默认）和翻译版本都能得到妥善提供。

来源：index.html22-39

主要的 HTML 结构

HTML 结构非常简洁，因为 Docsify 大部分内容是动态生成的。

文档内容在 Docsify 的 <div id="app"></div> 元素内渲染。

来源：index.html1-43

自定义样式

该存储库包含一个最小的自定义 CSS 文件（index.css），它提供了样式调整。

这确保了导航菜单项的正确格式。

来源：index.css1-3

该文档系统使用两个主要文件进行导航：

导航栏 (_navbar.md)

导航栏主要处理语言选择，提供多种语言的翻译。

此下拉菜单允许用户在课程的不同语言版本之间切换。

来源：docs/_navbar.md1-21

侧边栏 (_sidebar.md)

侧边栏提供了课程的目录，按章节和单独的课程进行组织。

侧边栏将课程按逻辑章节组织，每门课程按顺序编号。这种结构在存储库的文件夹组织中也有体现。

来源：docs/_sidebar.md1-37

PDF生成

该文档系统包括生成课程 PDF 版本的功能，使其可以以离线格式访问或用于打印。

PDF 生成配置

PDF 生成通过 docsifytopdf.js 配置文件进行控制。

此配置

  • 使用侧边栏文件作为 PDF 的目录
  • 输出到 pdf/readme.pdf
  • 设置 PDF 文档的页边距
  • 生成后清理临时文件
  • 使用“打印”媒体类型以获得最佳格式

来源：docsifytopdf.js1-10 package-lock.json1-149

PDF 生成流程

PDF 生成过程：

  1. 该过程通过运行 npm run convert 来触发。
  2. docsify-to-pdf 包读取侧边栏文件以确定内容结构。
  3. 它使用 Puppeteer（一个无头 Chrome 浏览器）来渲染内容。
  4. Docsify 将 Markdown 处理成 HTML。
  5. Puppeteer 使用指定的设置将 HTML 转换为 PDF。
  6. 最终的 PDF 将保存到指定位置。

来源：package.json6-8 docsifytopdf.js1-10 package-lock.json670-690

翻译处理

文档系统通过文件结构约定和 Docsify 配置设置的组合来处理翻译。

翻译文件结构

翻译遵循命名约定：

  • 英语文件：README.md
  • 翻译文件：README.[language-code].md

例如

  • 英语：README.md
  • 西班牙语：README.es.md
  • 法语：README.fr.md

URL 重写以进行翻译

Docsify 配置包含处理翻译 URL 模式的别名规则。

这些规则会将对翻译内容的请求路由到适当的文件。

  • 翻译文件位于 translations 文件夹中。
  • 英语文件位于主内容目录中。
  • 规则处理各种路径模式，以确保内容正确提供。

来源：index.html29-38 docs/_navbar.md1-21

托管和部署

该文档托管在 GitHub Pages 上，利用 GitHub 对开源项目的免费托管。

GitHub Pages 集成

GitHub Pages 自动提供存储库中的内容。设置很流畅，因为：

  1. Docsify 完全在浏览器中运行，无需构建步骤。
  2. GitHub Pages 只需提供静态文件（HTML、CSS、JavaScript）。
  3. 当用户访问网站时，Docsify 会动态渲染 Markdown 内容。

这种方法简化了部署，因为推送到存储库的任何更改都会立即反映在实时网站上。

关键组件的汇总表

组件文件目的
Docsify配置index.html配置文档系统设置
自定义样式index.css提供次要样式调整
导航栏docs/_navbar.md提供语言选择选项
侧边栏/TOCdocs/_sidebar.md组织课程内容
PDF 配置docsifytopdf.js配置 PDF 生成设置
PDF 脚本package.json包含 PDF 生成的 npm 脚本
内容各种 .md 文件实际的课程内容
翻译README.[lang].md 文件内容的翻译版本

来源： index.html1-43 index.css1-3 docs/_navbar.md1-21 docs/_sidebar.md1-37 docsifytopdf.js1-10 package.json1-28

使用文档系统

添加新内容

要为课程添加新内容

  1. 在适当的目录下创建一个 markdown 文件
  2. 更新侧边栏（docs/_sidebar.md），以包含新内容
  3. 如有必要，请遵循命名约定添加翻译

创建翻译

要添加新的翻译

  1. 创建一个文件名模式为 README.[语言代码].md 的文件
  2. 将语言添加到导航栏（docs/_navbar.md）
  3. 根据翻译指南翻译内容

生成 PDF

要生成文档的 PDF 版本

  1. 使用 npm install 确保依赖项已安装
  2. 运行命令 npm run convert
  3. 生成的 PDF 将在 pdf/readme.pdf 提供

结论

《Web Development for Beginners》的文档系统提供了一种轻量级、多功能的课程内容展示方式。通过利用 Docsify，该系统提供了动态内容渲染、多语言支持和 PDF 生成功能，而无需复杂的构建过程。这种方法非常符合课程的教学目标，使其能够以多种格式和语言供广大学习者访问。