0
点赞
收藏
分享

微信扫一扫

使用docsify构建gitlab pages文档库

大自然在召唤 2022-02-22 阅读 90
githubdocsifymarkdown数学公式

前几天策划写了一个word文档来整理补充一些内容，当时就比较感慨，如果是Web文档就好了，可以超链接过去，也不必东一个文档，西一个文档的查找。

确实如此，工作这么久，各个公司的策划案都是使用的Word文档的形式给别的部门，策划写起来是方便了，但是其他岗位的人要看文档来制作就比较麻烦了，比如程序，一个项目中可能会有几十甚至几百个文档，这些文档之间的内容可能会有相互关联，使用WORD文档，可能过段时间，策划自己都不知道放哪个文档了，于是就出了各种整理文档，补充文档。

使用Web来管理文档是好，但要让策划直接编写网页制作策划案，我想应该基本上没人响应。那就只能迂回一点，平常写博客这类的文档，使用最多的就是Markdown了，而且目前使用Markdown格式作为各种网络文档也是非常常见的，比如github、gitlab、CSDN、各种笔记类APP等等。

有了使用Web来管理策划案的想法后，就着手查资料开干。
查下来目前比较常见的工具有：

  1. jekyll
  2. gitbook
  3. Hexo
  4. Gatsby
  5. Hugo
  6. vuepress
  7. Docsify
  8. Docute
  9. Nuxt

笔者之前写过一篇《使用jekyll写博客》，就是介绍的使用jekyll来编写github的博客。
jekyll使用的ruby语言来构建静态网页，要使用这个工具，搭建语言环境比较麻烦，笔者在MacOS上为了使用jekyll，记得卡在了ruby的版本上，要求高版本，但OS又支持不了高版本，就此作罢，只能Windows上用用。

其它工具就不一一介绍了，都做了超链接，感兴趣的读者可以自行点开了解。今天要介绍是主角是Docsify，它与Docute一起成为与其它工具不一样的选择。

Docsify与Docute都是基于 Vue，且它们都是完全的运行时驱动，不会生成静态html，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们将是非常好的选择！在公司内部做策划文档的管理，不需要SEO，所以使用运行时驱动的Docsify或者Docute是完全可以的。之所以选择Docsify，一是因为最先发现它，二是它比Docute小，插件这些也比较丰富。

下面就介绍一下如何使用docsify构建gitlab Pages上的文档库。

一、开启gitlab pages

编辑/etc/gitlab/gitlab.rb，设置pages_external_url为自定义的域名，并且设置gitlab_pages[‘enable’]为true，如果要打开访问控制，则需要设置gitlab_pages[‘access_control’]为true，如下所示：

################################################################################
## GitLab Pages                                                             
##! Docs: https://docs.gitlab.com/ee/pages/administration.html                          
################################################################################
                                                                              
##! Define to enable GitLab Pages                                           
pages_external_url "http://pages.io/"                                                                   
gitlab_pages['enable'] = true 

##! Pages access control                                                                                    
gitlab_pages['access_control'] = true

设置好后运行下面的命令生效：

gitlab-ctl reconfigure

二、gitlab网站设置

1. 访问控制

如果需要访问控制，则需要：
在“菜单”=>“管理员”=>“设置”=>“偏好设置”中展开Pages选项，勾选

  • 要求用户证明自定义域名的所有权
  • 禁止公开访问 Pages 站点

如下图所示：
在这里插入图片描述
最大页面大小默认为100M，可以根据实际情况调整。设置完成后记得执行“保存修改”。

2. 项目设置

在开启Pages后，项目设置，通用里会根据项目可见性自动设置Pages的可见性，并且项目设置里会看到Pages栏，如下图所示：
在这里插入图片描述
此时还没有任何可用页面。

三、编写网页

使用docsify+markdown文件来构建网页，只需要编写一个index.html即可。其它的就是根据docsify规则 编写markdown文件。

本地编写markdown文件建议使用VSCode+Office Viewer(Markdown Editor)插件，Office Viewer(Markdown Editor)插件使用了vditor markdown编辑器，不得不说该编辑器非常强大。

如果想在本地编写好后，预览网页，满意后，再发布到gitlab pages。则需要在本地安装相应的环境。先安装node.js，再根据官方文档创建相应的项目。

具体如何编写这里就不再赘述了，可以看官方文档。官方文档给出了一个插件列表awesome-docsify，里面有很多插件，可以丰富docsify。

这里主要介绍一下官网上没有的或者需要注意的东西。

docsify内置的 Markdown 解析器是 marked，对markdown的支持有限，像数学公式，mermaid图这些都不支持，官网上对markdown的配置所提甚少，只提供了mermaid图的配置，数学公式没有提及。

下面结合awesome-docsify中提供的插件，介绍一下几种常用的额外功能配置：

1. mermaid图

直接使用插件docsify-mermaid；

	<!--mermaid图支持-->
    <script src="//unpkg.com/mermaid/dist/mermaid.js"></script>
    <script src="//unpkg.com/docsify-mermaid@latest/dist/docsify-mermaid.js"></script>
    <script>
      mermaid.initialize({ startOnLoad: true });
    </script>

2. plantuml图

直接使用插件docsify-plantuml 或者插件docsify-puml

<script>
      window.$docsify = {
		plantuml: {
          skin: "classic",
        },
     }
</script>     
<!--plantuml图支持-->
<script src="//unpkg.com/docsify-plantuml/dist/docsify-plantuml.min.js"></script>

3.数学公式

数学公式，这里需要提一下，markdown中的数学公式有几种格式，不同的平台支持的写法也不一致。
常见的markdown数学公式有以下几种写法：

  • 以$加`开头，并以反序结尾的行内公式（gitlab支持，vditor会多显示一对单引号）
  • 以$开头和结尾的行内公式（gitlab不支持，vditor支持）
  • 以$$开头和结尾的块公式（gitlab不支持，vditor支持）
  • 以math块标识的块公式（gitlab支持，vditor支持）

有一个插件docsify-katex 支持使用katex输出数学公式，但是试用了一下，没达到预期。docsify有一个issues提到怎样支持数学公式，但不尽如意。

笔者通过查资料和自己的修改得出如下配置：

<script>
      window.$docsify = {
      plugins: [
          function (hook) {
            // 支持$和$$
            hook.doneEach(function () {
              if (typeof MathJax !== "undefined") {
                MathJax.Hub.Queue(["Typeset", MathJax.Hub]);
              }
            });
            // 支持$``$
            hook.beforeEach(function (content) {
              return content.replace(/\$`.*`\$/g, function (a) {
                return a.replace("`", "").replace("`", "");
              });
            });
            // 支持```math```块
            hook.beforeEach(function (content) {
              return content.replace("\r\n","\n");
            });
            hook.beforeEach(function (content) {
              return content.replace("\r","\n");
            });
            hook.beforeEach(function (content) {
              c = content.replace(
                /```math\n[^`]*\n```/g,
                function (a) {
                  return a
                    .replace("```math", "\$\$\$\$")
                    .replace("```", "\$\$\$\$");
                }
              );
              return c
            });
          },
        ],
      }
</script>

<script type="text/x-mathjax-config">
      MathJax.Hub.Config({
      tex2jax: {
        inlineMath: [['$','$'], ['\\(','\\)']],
        displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
        processClass: 'math',
        processEscapes: true
      },
      TeX: {
      equationNumbers: { autoNumber: ['AMS'], useLabelIds: true },
      extensions: ['extpfeil.js', 'mediawiki-texvc.js'],
      Macros: {bm: "\\boldsymbol"}
      },
      'HTML-CSS': { linebreaks: { automatic: true } },
      'preview-HTML': { linebreaks: { automatic: true } },
      SVG: { linebreaks: { automatic: true } }
      });
</script>

<!--MathJax数学公式支持-->
<script src="//cdn.bootcss.com/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

下图为数学公式示例输出：
在这里插入图片描述

四、预览网页

预览网页只需要在项目所在目录的命令行运行：

docsify serve

五、发布到gitlab pages

1. 编写.gitlab-ci.yml

为了让gitlab pages能正常显示网页，需要使用到gitlab的CI/CD功能，在项目根目录创建一个.gitlab-ci.yml文件，也可以在gitlab网站上新建，选择.gitlab-ci.yml模板，应用html模板。
在这里插入图片描述
在这里插入图片描述
在这里插入图片描述
或者把生成的内容复制到本地建。

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

这样每次提交更改后，gitlab都会自动更新页面。
成功后就可以在项目设置的Pages下看到网页的访问地址了：

在这里插入图片描述

2. 修改hosts

由于前面在配置gitlab.rb时pages_external_url是随便配置的，为了能正常访问，需要将之映射到gitlab所在的ip，修改C:\Windows\System32\drivers\etc\hosts，添加映射：

192.168.1.6 docs.pages.io
192.168.1.6 projects.pages.io

docs.pages.io是平常访问用到的域名，其中的docs是gitlab中项目所在的组或者用户
projects.pages.io是访问控制授权时需要用到的域名。

六、附index.html源码

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="description" content="Description" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, minimum-scale=1.0"
    />
    <link
      rel="stylesheet"
      href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"
    />
  </head>

  <body>
    <div id="app"></div>
    <script>
      window.$docsify = {
        loadNavbar: true,
        loadSidebar: true,
        loadSidebar: "summary.md",
        autoHeader: true,
        subMaxLevel: 3,
        auto2top: true,
        name: "主页",
        homepage: 'index.md',
        basePath: 'docs',
        repo: "http://192.168.1.6/",

        pagination: {
          previousText: "上一篇",
          nextText: "下一篇",
          crossChapter: true,
          crossChapterText: false,
        },

        count: {
          countable: true,
          fontsize: "0.9em",
          color: "rgb(90,90,90)",
          language: "chinese",
        },

        search: {
          maxAge: 864, // 过期时间，单位毫秒，默认一天
          placeholder: "搜索",
          noData: "找不到结果",
          namespace: "文档",
        },

        plantuml: {
          skin: "classic",
        },

        timeUpdater: {
          text: ">最后更新时间: {docsify-updated}",
          formatUpdated: "{YYYY}/{MM}/{DD} {HH}:{mm}",
        },

        plugins: [
          function (hook) {
            // 支持$$
            hook.doneEach(function () {
              if (typeof MathJax !== "undefined") {
                MathJax.Hub.Queue(["Typeset", MathJax.Hub]);
              }
            });
            // 支持$``$
            hook.beforeEach(function (content) {
              return content.replace(/\$`.*`\$/g, function (a) {
                return a.replace("`", "").replace("`", "");
              });
            });
            // 支持```math```块
            hook.beforeEach(function (content) {
              return content.replace("\r\n","\n");
            });
            hook.beforeEach(function (content) {
              return content.replace("\r","\n");
            });
            hook.beforeEach(function (content) {
              c = content.replace(
                /```math\n[^`]*\n```/g,
                function (a) {
                  return a
                    .replace("```math", "\$\$\$\$")
                    .replace("```", "\$\$\$\$");
                }
              );
              return c
            });
          },
        ],
      };
    </script>
    <script type="text/x-mathjax-config">
      MathJax.Hub.Config({
      tex2jax: {
        inlineMath: [['$','$'], ['\\(','\\)']],
        displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
        processClass: 'math',
        processEscapes: true
      },
      TeX: {
      equationNumbers: { autoNumber: ['AMS'], useLabelIds: true },
      extensions: ['extpfeil.js', 'mediawiki-texvc.js'],
      Macros: {bm: "\\boldsymbol"}
      },
      'preview-HTML': { linebreaks: { automatic: true } },
      SVG: { linebreaks: { automatic: true } }
      });
    </script>
    <!-- Docsify v4 -->
    <script src="//cdn.jsdelivr.net/npm/docsify"></script>

    <!--MathJax数学公式支持-->
    <script src="//cdn.bootcss.com/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

    <!--plantuml图支持-->
    <script src="//unpkg.com/docsify-plantuml/dist/docsify-plantuml.min.js"></script>

    <!--mermaid图支持-->
    <script src="//unpkg.com/mermaid/dist/mermaid.js"></script>
    <script src="//unpkg.com/docsify-mermaid@latest/dist/docsify-mermaid.js"></script>
    <script>
      mermaid.initialize({ startOnLoad: true });
    </script>

    <!--字数统计-->
    <script src="//unpkg.com/docsify-count/dist/countable.js"></script>

    <!-- emoji表情支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
    <!-- 搜索功能支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
    <!--在所有的代码块上添加一个简单的Click to copy按钮来允许用户从你的文档中轻易地复制代码-->
    <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
    <!-- 图片放大缩小支持 -->
    <script src="//unpkg.com/docsify/lib/plugins/zoom-image.min.js"></script>
    <!--分页支持-->
    <script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
    <!-- 更新时间支持 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-updated@1/src/time-updater.min.js"></script>

    <!--语法高亮-->
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-c.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-cpp.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-csharp.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-go.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-go-module.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-cmake.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-lua.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-mermaid.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-protobuf.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-docker.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
  </body>
</html>
举报

相关推荐

使用vitepress构建组件库文档

ui前端javascript

gitlab-- pages 功能实战

gitdocker加载HarmonyOS后端开发

Docsify 使用教程

使用教程javaLinux系统/运维

使用 Github Pages 发布你的项目文档

JekyllWebHTMLLinux系统/运维

Git以及Gitlab的快速使用文档

chatgpt人工智能AIGC

使用Docsify快速搭建个人博客

经验分享

使用轻量应用服务器部署Docsify在线文档平台

轻量征文用户投稿阿里云

SchemaSpy：轻松构建数据库文档

数据库database

入坑 docsify，一款神奇的文档生成利器！

编程技术linux&g...程序员公众号：阿区先生UI设计一切linux运维技术想法

通过 jekyll 构建 github pages 博客实战笔记

GitHub
0 条评论