专业编程基础技术教程

网站首页 > 基础教程 正文

如何使用Doks做知识管理（doe知识）

ccvgpt 2024-07-21 17:39:52 基础教程 14 ℃

年初用Hugo搭建了个人博客，日常的一些想法和复盘都会记录在上面，写了大半年了，还是觉得博客不太能够满足个人的需求，博客虽然有标签、分类，也可以分享，但是没有那么的直观和好用。

我希望它可做个人站点的文档管理或者知识管理，多个相关联的文档能形成一个整体，当我用到的时候，可以直接导航到某个文档上。

如何使用Doks做知识管理（doe知识）

各方寻找，发现Hugo有一款主题Doks，刚好能满足我的需求。

花了些时间将Doks部署在了家里的NAS上，简单记录一下过程。

配置Docker

Doks是一个hugo版的docs项目，运行在node上，我们找的Docker镜像也需要能支持node。

可惜我找遍了Git Hub和Docker Hub一无所获，只能自己动手丰衣足食了，只要能实现自己的需求，多花点时间也是值得的。

各方查找后，找到了一个借鸡下蛋的方案，下面简单说说。

我的配置与部署是基于unraid的docker组件操作的，做了些简化。

第1步： 安装node简化版容器node:slim

docker run  
  -d  
  --name='MyDocs'  
  --net='swag'  //自定义网络
  --ip='172.18.0.19'  //固定ip
  --privileged=true  
  -e TZ="Asia/Shanghai"  
  -e HOST_OS="Unraid"  
  -e HOST_HOSTNAME="Tower"  
  -e HOST_CONTAINERNAME="MyDocs" 
  -l net.unraid.docker.managed=dockerman  
  -l net.unraid.docker.webui='http://[IP]:[PORT:8813]'  //unraid web ui
  -p '8813:1313/tcp'  //端口映射
  -v '/mnt/user/container/mydocs/':'/src':'rw'  //目录映射
  -w '/src' 'node:slim' tail -F anything  //用tail是为了后续安装hugo

这步最重要的是自定义网络，目录映射和发布参数的填写

第2步： 容器页面或者docker exec直接进入node容器，在根目录手动安装hyas和hugo-extended

在根目录安装hyas

npm create hyas@latest -- --template doks

按命令提示执行，中间会让输入安装目录，我的是doks

进入/doks目录，执行以下命令安装hugo-extended

npm install hugo-extended

装好后，为了避免后续重启容器，node没有权限调用hugo，或者安装文件丢失

可以用cp命令，将doks目录下的文件全部copy到src目录

cp -r /doks/* /src

再给当前用户755权限

chmod -R 755 node_modules/

装好后，接下来就可以改写package.json，让node调用hugo

找到scripts的命令参数，只改dev这一行，baseURL改成自己的域名服务

  "scripts": {
    "create": "hugo new",
    "dev": "hugo server --appendPort=false --baseURL='mydocs.yourdomain.com' --port=1313 --bind='0.0.0.0' --disableFastRender --noHTTPCache",
    "format": "prettier **/** -w -c",
    "build": "hugo --minify --gc",
    "preview": "vite preview --outDir public"
  }

第3步：发行参数改为npm run dev，重启容器

docker run  
  -d  
  --name='MyDocs'  
  --net='swag'  //自定义网络
  --ip='172.18.0.19'  //固定ip
  --privileged=true  
  -e TZ="Asia/Shanghai"  
  -e HOST_OS="Unraid"  
  -e HOST_HOSTNAME="Tower"  
  -e HOST_CONTAINERNAME="MyDocs" 
  -l net.unraid.docker.managed=dockerman  
  -l net.unraid.docker.webui='http://[IP]:[PORT:8813]'  //unraid web ui
  -p '8813:1313/tcp'  //端口映射
  -v '/mnt/user/container/mydocs/':'/src':'rw'  //目录映射
  -w '/src' 'node:slim' npm run dev  //node会执行hugo编译markdown文件

如果能看到如下页面，说明部署好了

doks

安装过程中，如有问题，可以先看看官网文档，或者评论区留言。

关于如何配合doks使用markdown，官方文档有详细的说明，这里说些最基本的用法。

目录结构

├── assets/                   //存放脚本，样式，图片资源
├── config/
│   └───_default/
│       ├───hugo.toml         //hugo的配置文件
│       ├───menus.toml        //菜单配置
│       ├───module.toml       //mounts配置
│       └───params.toml       //svg,seo配置
├── content/                  //hugo markdown目录
│   └───docs/
│       ├───guides/
│       │   ├───_index.md
│       │   └───getting-started.md
│       └───_index.md
├── layouts/                  //页面布局
├── node_modules/             //node安装包
├── public/                   //最终生成的目录
├── static/                   //静态资源fonts, favicon, PDFs
└── package.json              //node配置

Doks的目录结构大体上和hugo是一致的，后续的修改主要基于config和content目录

主页Home

站点主页的模版在layouts/index.html

Home页修改：

{{ define "main" }}
<section class="section container-fluid mt-n3 pb-3">
  <div class="row justify-content-center">
    <div class="col-lg-12 text-center">
      <h1>{{ .Title }}</h1>
    </div>
    <div class="col-lg-9 col-xl-8 text-center">
      <p class="lead">{{ .Params.lead | safeHTML }}</p>
      <a class="btn btn-primary btn-cta rounded-pill btn-lg my-3" href="/docs/{{ if site.Params.doks.docsVersioning }}{{ site.Params.doks.docsVersion }}/{{ end }}guides/example-guide/" role="button">{{ i18n "get_started" }}</a>
      {{ .Content }}
    </div>
  </div>
</section>
{{ end }}

具体内容需要改content/_index.md

---
title: "Welcome to Doks"
description: ""
lead: "Congrats on setting up a new Doks project!"
date: 2023-09-07T16:33:54+02:00
lastmod: 2023-09-07T16:33:54+02:00
draft: false
seo:
  title: "Welcome to Doks" # custom title (optional)
  description: "" # custom description (recommended)
  canonical: "" # custom canonical URL (optional)
  noindex: false # false (default) or true
---

{{ .Title }} {{ .Content }} {{ .Params.lead {{ i18n "get_started" }} 均是引用变量

模版里还可以修改footer

{{ define "sidebar-prefooter" }}
  {{ if site.Params.doks.backgroundDots -}}
  <div class="d-flex justify-content-start">
    <div class="bg-dots"></div>
  </div>
  {{ end -}}
  {{ if eq $.Site.Language.LanguageName "English" }}
  <section class="section section-md section-features">
    <div class="container">
      <div class="row justify-content-center text-center">
        <div class="col-lg-5">
          <h2 class="h4">更新</h2>
          <p>Edit <code>content/_index.md</code> to see this page change.</p>
        </div>
        <div class="col-lg-5">
          <h2 class="h4">Add new content</h2>
          <p>Add Markdown files to <code>content</code> to create new pages.</p>
        </div>
        <div class="col-lg-5">
          <h2 class="h4">Configure your site</h2>
          <p>Edit your config in <code>config/_default/hyas/doks.toml</code>.</p>
        </div>
        <div class="col-lg-5">
          <h2 class="h4">Read the docs</h2>
          <p>Learn more in the <a href="https://getdoks.org/">Docs</a>.</p>
        </div>
      </div>
    </div>
  </section>
  {{ end }}
{{ end }}

{{ define "sidebar-footer" }}
{{ if site.Params.doks.sectionFooter -}}
<section class="section section-md container-fluid bg-light">
  <div class="row justify-content-center text-center">
    <div class="col-lg-7">
      <h2 class="mt-2">Start building with Doks today</h2>
      <a class="btn btn-primary rounded-pill px-4 my-2" href="/docs/{{ if site.Params.doks.docsVersioning }}{{ site.Params.doks.docsVersion }}/{{ end }}prologue/introduction/" role="button">{{ i18n "get-started" }}</a>
    </div>
  </div>
</section>
{{ end -}}
{{ end }}

默认site.Params.doks.sectionFooter是不开启的，如果需要打开请修改config/_default/params.toml

其中有个多语言变量{{ i18n "get-started" }} ，这里可以看config/_default/module.toml的配置，自定义翻译可以按照挂载目录自行修改

## i18n
[[mounts]]
  source = "node_modules/@hyas/doks-core/i18n"
  target = "i18n"

[[mounts]]
  source = "i18n"
  target = "i18n"

此外，最底部Privacy Policy在config/_default/menus/menus.en.toml中有配置

[[footer]]
  name = "Privacy Policy"
  url = "/privacy/"
  weight = 10

底部右侧的小字- Brought to you by Hyas，可以到config/_default/languages.toml修改

[en]
  languageName = "English"
  contentDir = "content/en"
  weight = 10
  [en.params]
    languageISO = "EN"
    languageTag = "en-US"
    footer = 'Brought to you by <a class="text-muted" href="https://gethyas.com/">Hyas</a>'
    alertText = '<a class="alert-link stretched-link fw-normal" href="/blog/example-post/">Doks version 1.0 just shipped!</a>'

菜单Menu

菜单的配置在config/_default/menus/menus.en.toml

[[guide]]
  name = "Lorem"
  weight = 10
  identifier = "lorem"
  url = "/guide/lorem/"

[[main]]
  name = "Docs"
  url = "/docs/guides/example-guide/"
  weight = 10

[[main]]
  name = "Blog"
  url = "/blog/"
  weight = 30

[[social]]
  name = "GitHub"
  pre = '<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-brand-github" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M9 19c-4.3 1.4 -4.3 -2.5 -6 -3m12 5v-3.5c0 -1 .1 -1.4 -.5 -2c2.8 -.3 5.5 -1.4 5.5 -6a4.6 4.6 0 0 0 -1.3 -3.2a4.2 4.2 0 0 0 -.1 -3.2s-1.1 -.3 -3.5 1.3a12.3 12.3 0 0 0 -6.2 0c-2.4 -1.6 -3.5 -1.3 -3.5 -1.3a4.2 4.2 0 0 0 -.1 3.2a4.6 4.6 0 0 0 -1.3 3.2c0 4.6 2.7 5.7 5.5 6c-.6 .6 -.6 1.2 -.5 2v3.5"></path></svg>'
  url = "https://github.com/gethyas/doks"
  post = "v0.1.0"
  weight = 30

[[footer]]
  name = "Privacy Policy"
  url = "/privacy/"
  weight = 10

菜单的配置的其它参数可以参考hugo的官方文档

主要的参数有以下几个：

  • identifier，菜单id
  • name，菜单name
  • parent，父菜单id
  • pageRef，跳转内部链接
  • url，跳转外部链接
  • weight，显示顺序

这些参数的搭配，可以创建子菜单，以及调整顺序和跳转

博客Blog

├── content/
│   └───blog/
│       ├───example/
│       │   ├───index.md
│       └───_index.md

这个目录结构刚开始有点蒙，熟悉了hugo之后就很容易理解了，

_index.md文件是一个用来检索的特殊md文件，不含实质内容，页面显示时，会解析当前路径以及子路径下的所有md文件

index.md标识example路径下的默认文件，该文件夹下的其它文件只会做为资源被引用

平常新增md文件，在blog子目录下新建后，会自动被解析，需要注意的是frontmatter的几个属性

---
title: "Blog"
description: ""
summary: ""
date: 2023-09-07T16:21:44+02:00
lastmod: 2023-09-07T16:21:44+02:00
draft: false
weight: 50
categories: []
tags: []
toc: false
---

每篇文章设置好文档属性后，以后搜索和查询就方便了很多。

Doks还支持卡片，短代码，数学公式，流程图等等，这里不再赘述，需要的时候看看官网的文档。

这里特别讲一下插图和卡片，先看下效果

用短代码怎么写呢？记得两两配对就可以

{{< callout tip >}} This is a note callout. {{< /callout >}}

{{< details "Details" >}} 折叠文章内容，点击右三角{{< /details >}}


{{< card-grid >}}
{{< link-card title="点我跳转" href="/showcase/" >}}
{{< link-card title="点我跳转" href="/showcase/" >}}
{{< /card-grid >}}

导航Docs

之前已经在config/_default/menus/menus.en.toml中，写过如何配置菜单的跳转

[[main]]
  name = "Docs"
  url = "/docs/guides/example-guide/"
  weight = 10

但并不是所有的菜单，点进去展示的都需要导航栏，默认配置的是docs，config/_default/params.toml里，也可以修改为其它

  # Nav
  sectionNav = ["docs"] # ["docs"] (default) or list of sections (e.g. ["docs", "guides"])

还可以自定义侧边栏和跳转，sidebar_docs指的是菜单名称，配置好后，便不会自动生成

[[sidebar_docs]]
  name = "Guides"
  pageRef = "/docs/guides"
  weight = 10

[[sidebar_docs]]
  name = "Reference"
  pageRef = "/docs/reference"
  weight = 20

关于目录，doks支持在/config/_default/markup.toml配置生成目录生成的层级，如果某篇文章不想要目录，文档属性里请把把toc设置为false

[tableOfContents]
  endLevel = 3
  ordered = false
  startLevel = 2

试了几番，最后可以看到这个样子

看起来是不是很舒服，断断续续码字，终于写完了，如果您觉得有用的话，记得点赞收藏加关注哦。

Tags：

猜你喜欢

最近发表
标签列表