https://docs.njet.org.cn/contrib/v1.0/index.html 本章节描述如何编写NJet文档，也作为一个样例，体现NJet文档管理中的各种能力及要求 Hugo zh https://docs.njet.org.cn/contrib/v1.0/intro/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/intro/index.html OpenNJet文档编写指南 OpenNJet文档采用多页HTML展示，主要由QA人员编写MD文件，利用hugo工具渲染为多页HTML，其主题采用relearning，主要利用其特有的多版本能力。 工作流 graph LR; 管理员创建文档仓库-->拉取仓库-为每个版本创建一个站点-->创建版本化的md文档-->利用hugo本地site测试-->提交CI自动产生静态站点部署 初始目录结构 njet_doc Readme.md .gitignore relearn hugo.toml … 从仓库check出来，文档目录顶层结构包括 relearn 目录，hugo.toml,以及已经创建的不同版本的文档，不同的版本每个用独立的目录 利用hugo 命令创建站点 hugo new site “{version}” 链接 relearning主题到站点的themes下 用上层hugo.toml替换产生的hugo.toml, 删除site下的archtypes的内容， hugo new site v1.0 cd v1.0 rm hugo.toml ln -s ../hugo.toml hugo.toml cd themes/ ln -s ../../relearn/ relearn 备注 依赖hugo extend 0.148 extend 及以上 hugo version hugo v0.148.2-40c3d8233d4b123eff74725e5766fc6272f0a84d+extended linux/amd64 BuildDate=2025-07-27T12:43:24Z VendorInfo=gohugoio 安装hugo CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest https://docs.njet.org.cn/contrib/v1.0/compose/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/compose/index.html 创建文档 Caution 创建文档需要利用hugo 命令创建md文件，以增加必要的front matter信息 hugo new content "xxxx.md" 或 hugo new content "{sec}/xxxx.md" 前者在content下创建，后者在content/sec下创建 Caution 1 创建文档后，如果hugo serve不渲染出来，则可能是frontmatter中的draft = true， 默认hugo 是不会渲染草稿的 2 创建文档时，用英文名称 编写内容 编写内容使用markdown语法及扩展，相信格式需参考：relearning markdown 语法参考 https://docs.njet.org.cn/contrib/v1.0/menu/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/menu/index.html - 根据目录结构自动产生菜单 本工具链可以自动根据目录结构及文件类型生成嵌套的左侧的菜单栏 如下面的目录结构： content _index.md intro.md menu index.md menu-auto.png compose _index.md attach index.md njet-logo.png pictures index.md 产生的菜单如下图 - 菜单项控制 - 名称 来源于frontmatter中的 "title" +++ title = "菜单管理" weight=3 editUrl = "https://192.168.30.120/-/ide/project/njet_dev/njetdoc_contrib/edit/main/v1.0/content/${FilePath}" +++ - 排序 由frontmatter中的“weight”控制 - 嵌套 由目录结构确定 - toc 根据md文件中的header自动产生 - 额外菜单 在hugo.toml中可以配置额外菜单，比如 [menu] [[menu.shortcuts]] name = '阅读NJet文档' url = 'https://docs.njet.org.cn' weight = 1 详细阅读：https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/menus/index.html https://docs.njet.org.cn/contrib/v1.0/versioning/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/versioning/index.html 编写的NJet文档，支持多版本，可以直接在界面上选择对应的版本进行查看。NJet文档的多版本是通过不同的site的进行控制，每个版本对应一个site 创建新版本 root Readme.md .gitignore relearn hugo.toml v1.0 从仓库check出来，文档目录顶层结构包括 relearn 目录，hugo.toml,以及已经创建的不同版本的文档，不同的版本每个用独立的目录，比如仓库中存在版本v1.0,则目录结构如上图 通过 new site 命令创建新版本v2.0 hugo new site v2.0 新目录结构如下： root Readme.md .gitignore relearn hugo.toml v1.0 v2.0 增加版本切换 需修改hugo.toml增加新版本信息，并把latest指向新的版本 原配置 version = 'v1.0' [[params.versions]] baseURL = 'http://docs.njet.org.cn/contrib/v1.0/' identifier = 'v1.0' title = 'latest' 新配置 version = 'v2.0' [[params.versions]] baseURL = 'http://docs.njet.org.cn/contrib/v1.0/' identifier = 'v1.0' title = 'v1.0' [[params.versions]] baseURL = 'http://docs.njet.org.cn/contrib/v2.0/' identifier = 'v2.0' title = 'latest' https://docs.njet.org.cn/contrib/v1.0/edit/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/edit/index.html 利用 hugo new content xxx创建的内容，默认是具备在线编辑能力的，在NJet开发人员的内网中，并具备该仓库权限的人员，可以直接通过右上角的编辑按钮通过gitlab ide进行编辑，并在保存后可以发布在内网中 https://docs.njet.org.cn/contrib/v1.0/webserver/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/webserver/index.html 由于是多个站点实现多个版本 因此 需要这样每个版本分别一个location 这个是 contrib 文档 (NJet文档编写指南) location / { root /html/; } njet 目录结构 contrib 目录为 NJet文档编写指南 docs 目录为 NJet文档主站 $ tree /html -L 2 /html ├── contrib │ ├── v1.0 │ └── v2.0 └── docs ├── v3.3.0 └── v3.3.1 contrib 网站生成步骤 cd v1.0 && hugo build && sudo cp -r public/* /html/contrib/v1.0 cd v2.0 && hugo build && sudo cp -r public/* /html/contrib/v1.0 https://docs.njet.org.cn/contrib/v1.0/release/index.html Mon, 01 Jan 0001 00:00:00 +0000 https://docs.njet.org.cn/contrib/v1.0/release/index.html 发布流程 graph LR; a["本地测试"] --推送-->b[("main分支")]--ci推送到预览网站-->c{预览} c-->|发现问题|e["在线修改"] e--推送-->b b--合并-->r[("release分支")]-->p[ci推送到正式网站] CI 采用hugo命令产生静态网站内容，会产生在site的public目录下 hugo build 产生的public里的内容应推送到对应网站的hugo.toml中配置的对应版本的baseUrl下 配置 预览网站： https://preview.docs.njet.org.cn 实际为192.168.40.40 正式网站： https://docs.njet.org.cn, 实际为 192.168.40.250 contrib仓库地址： https://192.168.30.120/njet_dev/njetdoc_contrib.git 文档仓库地址：https://192.168.30.120/njet_dev/njetdoc.git