HUGO 自定义主题

创建一个主题

1# 在项目根目录下执行
2$ hugo new theme [newTheme] 
3#会在项目的theme文件夹下创建对应名字的主题, 例如：/theme/newTheme/
4
5# 在配置文件设置新创建的主题 /config.toml
6theme = 'newTheme' #启动项目后生效

文件结构说明

 1./theme # 项目的主题目录
 2    |__newTheme #新建的主题目录
 3        |__archetypes #新建页面时的扉页模版
 4            |__default.md #默认的扉页模版
 5            |__posts.md # 在 posts 分组下新建页面的扉页模版 优先级比 default 高
 6        |__assets # Hugo Pipes 的资源(css, js),通过.Permalink,.RelPermalink 引用发布到项目 public
 7            |__style.css # 主题用到的 css 文件
 8        |__layout #页面的模版文件
 9            |__default # 页面默认默认模版位置
10                |__baseof.html #站点的主框架,首先要加载的内容
11                |__index.html #首页模版 Kind 为 home 的页面会匹配该模版
12                |__list.html #分组模版 Kind 为 section 的页面会匹配该模版
13                |__single.html #单页面模版 Kind 为 page 的页面会匹配该模版
14            |__partials # 放一些子模块
15        |__static #主题使用到的 img...
16        |__theme.toml #主题配置文件

应用主题

在配置文件中配置主题

1<!-- config.toml -->
2theme = 'newTheme'

Hugo Theme 是如何工作的？

页面加载流程

1. 加载主题内站点的主框架 baseof.html
2. 根据页面的 Kind 属性匹配 /layout 下面的模版文件

   №	Page.Kind	Template
   0	home	index.html
   1	section	list.html
   2	page	single.html

3. 执行模版文件的模版语法 加载相应的子模块
4. 生成完整的静态页面

匹配模版的优先级

• /layout 的优先级 高于 /theme/newTheme/layout

css 文件引用

• css 样式文件位于 ./assets 文件夹内

• 站点使用的样式文件一般在 head 标签内引入

• ./layout/_default/baseof.html 站点框架文件包含完整的html格式 head 和 body

• 将 head 部分模块化为 ./layout/partials/head.html

• 在 head 模块内引入 css 样式文件

    {{ $style := resources.Get "scss/style.scss" }}
    {{ $a := $style | resources.ToCSS }}
    <link rel="stylesheet" href="{{ $a.Permalink }}">
  

• 在模版文件的元素就可以使用相应的样式了

使用 Tailwind CSS 框架

1. 通过 Node Package Manager 管理三方依赖库

   1# 在自定义主题文件夹下执行
   2$ npm init -y
   

2. 安装Tailwind CSS 依赖库

   1npm install -D tailwindcss
   

3. 初始化 Tailwind CSS

   1npx tailwindcss init
   2# 在主题根目录下会生成 tailwind.config.js 和 tailwind.css 
   

4. 配置模板路径

   1//tailwind.config.js
   2module.exports = {
   3    //在tailwind.config.js文件中添加所有模板文件的路径。
   4    content: ['content/**/*.md', 'layouts/**/*.html'],
   5}
   

5. 将Tailwind指令添加到 tailwind.css 中

   1@tailwind base;
   2@tailwind components;
   3@tailwind utilities
   

6. 在package.json, 在scripts 部分添加build和watch命令
   运行CLI工具来扫描模板文件的类并构建CSS。

   1"scripts": {
   2    // 编译 ./tailwind.css 文件输出到 ./assets/style.css
   3    "build": "npx tailwindcss -i ./tailwind.css -o ./assets/style.css",
   4    // 监听页面使用的 css ,实时更新到 ./assets/style.css
   5    "watch": "npx tailwindcss -i ./tailwind.css -o ./assets/style.css --watch"
   6}
   

7. 自定义 tailwind 的值时需要监听

   1$ npm run watch
   

8. 打包部署前 编译 ./tailwind.css

   1$ npm run build
   

9. 在 head 里面引用编译好的样式文件

   1<!--  注意 文件的路径为编译后输出到 ./ assets/ 下的路径 -->
   2{{ $tailwindcss := resources.Get "style.css" }}
   3<link rel="stylesheet" href="{{ $tailwindcss.Permalink }}">
   

10. markdown 语法插件 typography

     1    # 需要引入 tailwindcss 的插件
     2    npm install -D @tailwindcss/typography
     3    # 在模版语法 {{ .Content }} 的外层元素使用 class prose
     4    <article class="prose">
     5        {{ .Content }}
     6    </article>
     7    # class 灰度 prose-gray prose-slate prose-zinc prose-neutral prose-stone
     8    # class 大小 prose-sm prose-base prose-lg prose-xl prose-2xl
     9    # class 适应深色模式 dark:prose-invert
    10    # class 修改单个元素样式 prose-headings:underline prose-a:text-blue-600
    11    # 元素指示器 详见 https://tailwindcss.com/docs/typography-plugin#element-modifiers
    

11. 修改 tailwind 的基础样式

     1<!-- //newTheme/tailwind.css -->
     2@tailwind base;
     3@tailwind components;
     4@tailwind utilities;
     5<!-- //修改基础样式 -->
     6@layer base {
     7    h1,
     8    h2,
     9    h3,
    10    h4,
    11    h5,
    12    h6 {
    13        font-size: revert;
    14        font-weight: revert;
    15    }
    16    dl, dd {
    17        margin: revert;
    18    }
    19
    20    ol, ul {
    21        padding: unset;
    22    }
    23}
    

12. 修改 typography 的默认样式

     1// newTheme/tailwind.config.js
     2/** @type {import('tailwindcss').Config} */
     3const plugin = require('tailwindcss/plugin')
     4module.exports = {
     5    corePlugins: {
     6        preflight: true,
     7    },
     8    content: ['content/**/*.md', 'layouts/**/*.html'],
     9    theme: {
    10        extend: {
    11            // 自定义 typography 插件样式
    12            typography: {
    13                DEFAULT: {
    14                    css: {
    15                        // 文章展示区域的最大宽度
    16                        'max-width': '90ch',
    17                        // 二级目录的边距
    18                        h2: {
    19                            'margin-top': 'unset',
    20                            'margin-bottom': 'unset'
    21                        },
    22                        // 任何元素与二级目录的上边距
    23                        'h2 + *': {
    24                            'margin-top': '1.25em'
    25                        },
    26                        // 段落与任何元素的上边距
    27                        '* + p': {
    28                            'margin-top': '1.25em'
    29                        },
    30                        // 去掉 code 元素的开头与结尾的单引号
    31                        'code::before': {
    32                            content: 'none'
    33                        },
    34                        'code::after': {
    35                            content: 'none'
    36                        },
    37
    38                        'blockquote  p:first-of-type::before': {
    39                            content: 'none'
    40                        },
    41                        'blockquote  p:last-of-type::after': {
    42                            content: 'none'
    43                        },
    44                        'blockquote  p': {
    45                            'font-style': 'normal',
    46                            'font-weight': '300'
    47                        },
    48                        // 表格单元格内容垂直居中
    49                        'tbody td': {
    50                            'vertical-align': 'middle'
    51                        }
    52                    }
    53                },
    54            },
    55        },
    56    }
    57}