使用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 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 publicgit initgit add -Agit commit -m "first commit"git remote add origin  coderName/coderName.github.io.gitgit push -u origin master

• 后续升级提交，先要生成页面：hugo –buildDrafts

  cd publicgit add -Agit 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