使用Hugo生成支持数学公式渲染的静态站

hugo安装

• 下载hugo

• 新建D:\Hugo\bin，并将hugo.exe放入其中

• 将上述路径追加到环境变量

• 建立hugo工程

  • 建立项目工程工作文件夹，D:\Hugo\Blog

  • 命令行进入Blog，建立站点，D:\Hugo\Blog>hugo new site BlogCMS

  • 生成项目目录结构如下

    BlogCMS
        |--archetypes
        |--content
        |--data
        |--layouts
        |--static
        |--themes
    

• 安装主题，皮肤下载,查看其git链接

  • git官网下载
  • 命令行进入项目的themes文件夹
  • 使用git CMD下载皮肤到themes文件夹下,git clone https://github.com/matcornic/hugo-theme-learn.git

• 添加页面

  • 命令行进入BlogCMS
  • hugo命令：hugo new about.md
  • hugo命令：hugo new post/first.md(注意在该主题中，markdown文件名会被作为文章名)

• 菜单层级通过文件夹的嵌套来实现

  • 在每个文件夹的外面添加“_index.md”,并命名title，再添加内容；作为此一级菜单的首页
  • 属于该层级下的文件，均放入文件夹中

• 在站点的根目录，运行hugo：hugo server --theme=hugo-theme-learn --buildDrafts

• 在浏览器打开预览:http://localhost:1313

• Ctrl+C终止本地预览

• hugo更多详细信息请看在线教程

部署到GitHub

• 在GitHub上创建一个Repository，命名为coderName.github.io(coderName为github用户名)

• 在站点根目录执行Hugo命令，生成最终页面：hugo --theme=hugo-theme-learn --baseUrl="http://coderName.github.io/"

  • 或者在config.toml中配置baseURL = "http://coderName.github.io/"（预览时使用"http://example.org/"）
  • 内容页生成，需要--buildDrafts

• 所有静态页面都会生成到public目录中，将public目录里所有文件push到刚创建的Repository的master分支。

  cd public
  git init
  git add -A
  git commit -m "first commit"
  git remote add origin https://github.com/coderName/coderName.github.io.git
  git push -u origin master
  

• 后续更新提交，先要生成页面：hugo --buildDrafts

  cd public
  git add -A
  git commit -m "更新说明"
  git push -u origin master
  

• 在浏览器访问：http://coderName.github.io/

主题修改

• 让文章支持数学公式Katex渲染

  • 在主题hugo-theme-learn中，向custom-header.html中，添加如下一行

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css"/>
    

  • 在主题hugo-theme-learn中，向custom-footer.html中，添加如下两行

    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.js"
    integrity="sha384-K3vbOmF2BtaVai+Qk37uypf7VrgBubhQreNQe9aGsz9lB63dIFiQVlJbr92dw2Lx" 
    crossorigin="anonymous"></script>
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/contrib/auto-render.min.js"
    integrity="sha384-kmZOZB5ObwgQnS/DuDg6TScgOiWWBiVt0plIRkZCmE6rDZGrEOQeHM5PcHi+nyqe"
    crossorigin="anonymous"
    onload="renderMathInElement(document.body,{delimiters: [{left: '$$', right: '$$', display: true},{left: '$', right: '$', display: false}]});"></script>
    

  • 书写完markdown文件后，部分公式无法渲染。如多行公式无法换行，公式下标问题。因为markdown和katex中，“\”和"_"的渲染冲突造成,暂时没找到解决办法。

• 支持公式渲染的第二个方案：MathJax

  • 在主题hugo-theme-learn中，向custom-header.html中，添加如样式

        .hasJax{
        font: inherit;
        font-size: 100%;
        background: inherit;
        border: inherit;
        /*color: #515151;*/
    } 
    

  • 在主题hugo-theme-learn中，向custom-footer.html中，添加如下两行

    <script type="text/x-mathjax-config">
        MathJax.Hub.Config({
            tex2jax: {
                inlineMath: [['$','$'], ['\\(','\\)']],
                displayMath: [['$$','$$'], ['\[','\]']],
                processEscapes: true,
                processEnvironments: true,
                skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
                TeX: {
                    equationNumbers: { autoNumber: "AMS" },
                    extensions: ["AMSmath.js", "AMSsymbols.js"]
                }
            }
        });
    </script>
    <script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"></script>
    

  • 书写完markdown文件后，将无法正常显示的公式放到<div class='hasJax'></div>中:解决mathjax多行公式换行、下角标符号与markdown的冲突问题。

• 支持公式渲染的第三个方案：仍然是Katex，目前优先使用的是该方案

  • 在主题hugo-theme-learn中，向custom-header.html中，添加如样式

    <link rel="stylesheet" href="/katex/katex.min.css"/>
    

  • 在VSCode中编辑markdown文件，使用markdown-preview-enhenced插件预览，选择里层body中的内容，复制

  • 在hugo新建的md页面中粘贴上一步复制的内容，大功告成，打完收工

  • 这种方案有几个优点：因为是完成渲染，只需要添加一个css样式引用，不需要js引用；速度更快一些；反爬效果好，同时可能对搜索引擎不大友好；可以再添加其他样式。

• 注意主题的修改，都在custom-header.html和custom-footer.html中，尽量避免直接在header.html和footer.html中修改；为修改背景，在header.html中id为body的section元素添加了“class=theme-sepia”

• logo修改，在logo.html

  • logo点击链接到主页
  • 使用天空字体在线编辑logo：“究尽数学”，方正行楷简体+64大小+svg格式+背景透明
  • 将logo替换到logo.html

• 修改菜单底部，在menu-footer.html

• 自定义主页，主题在主页中写了三种方式

  • 在content文件夹下创建一个_index.md,并填充内容；
  • 在static文件夹中创建一个index.html文件，并填充它；
  • 配置服务器自动重定向到站点的一个文档页。

• 第四种自定义主页方式，直接修改index.html

• config.toml中站点title修改，

• 网站标志ICON修改，在主题的static/images中替换favicon.png;在朝夕网压缩图标

请关注公众号“究尽中学数学”和“究尽数学”，点击菜单“究尽数学”，参考查看我使用Hugo生成的静态站。

究尽数学.jpg
究尽中学数学.jpg