渤海深处的博客
所有文章 标签 分类 关于 首页
渤海深处的博客

目录

文章撰写 Markdown Shortcode 语法相关

 收录于 Markdown shortcodes
   约 3745 字   预计阅读 8 分钟    次

边学边手搓

文章前置参数

Hugo 允许在文章内容前面添加 yaml, toml 或者 json 格式的前置参数.

在LoveIt主题下，主要参数包括：

  • title: 文章标题.

  • subtitle: 文章副标题.

  • date: 这篇文章创建的日期时间. 它通常是从文章的前置参数中的 date 字段获取的, 但是也可以在 网站配置 中设置.

  • lastmod: 上次修改内容的日期时间.

  • draft: 如果设为 true, 除非 hugo 命令使用了 –buildDrafts/-D 参数, 这篇文章不会被渲染.

  • author: 文章作者.

  • authorLink: 文章作者的链接.

  • description: 文章内容的描述.

  • license: 这篇文章特殊的许可.

  • images: 页面图片, 用于 Open Graph 和 Twitter Cards.

  • tags: 文章的标签.

  • categories: 文章所属的类别.

  • featuredImage: 文章的特色图片.

  • featuredImagePreview: 用在主页预览的文章特色图片.

  • hiddenFromHomePage: 如果设为 true, 这篇文章将不会显示在主页上.

  • hiddenFromSearch: 如果设为 true, 这篇文章将不会显示在搜索结果中.

  • twemoji: LoveIt 如果设为 true, 这篇文章会使用 twemoji.

  • lightgallery: 如果设为 true, 文章中的图片将可以按照画廊形式呈现.

  • ruby: LoveIt 如果设为 true, 这篇文章会使用 上标注释扩展语法.

  • fraction: LoveIt 如果设为 true, 这篇文章会使用 分数扩展语法.

  • fontawesome: LoveIt 如果设为 true, 这篇文章会使用 Font Awesome 扩展语法.

  • linkToMarkdown: 如果设为 true, 内容的页脚将显示指向原始 Markdown 文件的链接.

  • rssFullText: 如果设为 true, 在 RSS 中将会显示全文内容.

  • toc: 和 网站配置 中的 params.page.toc 部分相同.

  • code: 和 网站配置 中的 params.page.code 部分相同.

  • math: 和 网站配置 中的 params.page.math 部分相同.

  • mapbox: 和 网站配置 中的 params.page.mapbox 部分相同.

  • share: 和 网站配置 中的 params.page.share 部分相同.

  • comment: 和 网站配置 中的 params.page.comment 部分相同.

  • library: 和 网站配置 中的 params.page.library 部分相同.

  • seo: 和 网站配置 中的 params.page.seo 部分相同.

Markdown 基本语法

文章使用 Markdown 书写，所以必须了解相关语法。

标题

从 h2 到 h6 的标题在每个级别上都加上一个 ＃:

## h2 标题
### h3 标题
#### h4 标题
##### h5 标题
###### h6 标题

注释

注释是和 HTML 兼容的：

<!-- 这是一段注释 -->

水平线

  • ___: 三个连续的下划线
  • ---: 三个连续的破折号
  • ***: 三个连续的星号

呈现的输出效果如下:

段落

按照纯文本的方式书写段落, 可以使用一个空白行进行换行.

内联 HTML 元素

如果需要某个 HTML 标签 (带有一个类), 则可以简单地像这样使用:

Markdown 格式的段落.

<div class="class">
    这是 <b>HTML</b>
</div>

Markdown 格式的段落.

需要注意的是默认无法渲染HTML内容，必须在config.toml里添加：

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

强调

加粗

用于强调带有较粗字体的文本片段.

以下文本片段会被 渲染为粗体.

**渲染为粗体**
__渲染为粗体__

斜体

用于强调带有斜体的文本片段.

以下文本片段被 渲染为斜体.

*渲染为斜体*
_渲染为斜体_

删除线

呈现的输出效果如下:

这段文本带有删除线.

~~这段文本带有删除线.~~

引用

用于在文档中引用其他来源的内容块.

在要引用的任何文本之前添加 >:

> **如下所示** 内容为引用.

如下所示 内容为引用.

可以嵌套

> **如下所示** 内容为嵌套引用.
>> 第二层

如下所示 内容为嵌套引用.

第二层

列表

无序列表

使用以下任何符号来表示无序列表中的项:

* 一项内容
- 一项内容
+ 一项内容

例如：

* 一项内容
  * 次要内容

显示效果：

  • 一项内容
    • 次要内容

有序列表

使用 1.,2.… 来编号

1. wa
2. wa

显示效果：

  1. wa
  2. wa

也可以全部用 1. ,Markdown 将自动为每一项顺序编号.

任务列表

可以创建带有复选框的列表. 要创建任务列表, 请在任务列表项之前添加破折号 (-) 和带有空格的方括号 ([ ]). 要选择一个复选框，请在方括号之间添加 x ([x]).

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

显示效果：

  • Write the press release
  • Update the website
  • Contact the media

代码

行内代码

用 ` 包装行内代码段. `得用

``` ` ``` 或者 `` ` `` 才打的出来...

在这个例子中, `<section></section>` 会被包裹成 **代码**.

显示效果：

在这个例子中, <section></section> 会被包裹成 代码.

缩进代码

将几行代码缩进至少四个空格，例如:

    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code

显示效果：

// Some comments
line 1 of code
line 2 of code
line 3 of code

围栏代码块

使用 “围栏” ``` 来生成一段带有语言属性的代码块. linenos=true用于行编号

```Markdown {linenos=true}
Sample text here...
```

显示效果：

1

Sample text here...

highlight 代码块

使用highlight来生成代码块，使用以及行号参数配置详见syntax-highlighting.

1
2
3

{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
// ... code
{{< / highlight >}}

注意 在代码块中内嵌代码块需要在每一个<后添加/*，在>前添加*/来防止shortcode被解析.

语法高亮

只需在第一个代码 “围栏” 之后直接添加你要使用的语言的文件扩展名, ```js, 语法高亮显示将自动应用于渲染的 HTML 中. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

```js
grunt.initConfig({
assemble: {
    options: {
    assets: 'docs/assets',
    data: 'src/data/*.{json,yml}',
    helpers: 'src/custom-helpers.js',
    partials: ['src/partials/**/*.{hbs,md}']
    },
    pages: {
    options: {
        layout: 'default.hbs'
    },
    files: {
        './': ['src/templates/pages/index.hbs']
    }
    }
}
};
```

显示效果如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

grunt.initConfig({
assemble: {
    options: {
    assets: 'docs/assets',
    data: 'src/data/*.{json,yml}',
    helpers: 'src/custom-helpers.js',
    partials: ['src/partials/**/*.{hbs,md}']
    },
    pages: {
    options: {
        layout: 'default.hbs'
    },
    files: {
        './': ['src/templates/pages/index.hbs']
    }
    }
}
};

表格

通过在每个单元格之间添加竖线作为分隔线, 并在标题下添加一行破折号 (也由竖线分隔) 来创建表格. 注意, 竖线不需要垂直对齐.

1
2
3
4
5

| Option | Description |
| :------: | ----------- |
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |

显示效果如下：

Option Description
data path to data files to supply the data that will be passed into templates.
engine engine to be used for processing templates. Handlebars is the default.
ext extension to be used for dest files.

在任何标题下方的破折号右侧添加冒号将使该列的文本右对齐.

在任何标题下方的破折号两边添加冒号将使该列的对齐文本居中.

:------:: 居中

------:: 右对齐

:------: 左对齐，（无冒号默认）

链接

基本链接

1
2
3

<https://assemble.io>
<contact@revolunet.com>
[Assemble](https://assemble.io)

显示效果：

https://assemble.io

contact@revolunet.com

Assemble

添加一个标题

1

<a href="https://github.com/upstage/" title="这是提示">Upstage</a>

悬浮会有提示，显示效果：

Upstage

定位标记

定位标记使你可以跳至同一页面上的指定锚点. 例如, 每个章节:

1
2
3
4

## Table of Contents
  * [Chapter 1](#chapter-1)
  * [Chapter 2](#chapter-2)
  * [Chapter 3](#chapter-3)

#后面跟的是id号，即回跳转到如下指定id的部分，建议将<a id="xxx"></a>放在标题往上单独一行

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<a id="chapter-1"></a>

## Chapter 1 
Content for chapter one.
<a id="chapter-2"></a>

## Chapter 2 
Content for chapter one.
<a id="chapter-3"></a>

## Chapter 3 
Content for chapter one.

注意 注意，不要直接在章节名后面加<a id="xxx"></a>，LoveIt主题官方文章说可以放一行，但是这样会出现两个问题：

  1. 会更改标题的id

例如标题#### 定位标记，它自动生成的id是id="定位标记",这个id主要用于目录索引

如果把<a id="xxx"></a>放在和标题一行，即#### 定位标记 <a id="xxx"></a>，会导致它自动生成的id变成id="定位标记-a-idxxxa",虽然目录索引会保持一致，不会影响目录跳转，但是如果自己去索引的话，可能不会注意到id产生了变化

  1. 会导致a标签重复生成

在目录索引处会生成一个<a id="xxx"></a>标签，然后在文章目录下面又会生成一个<a id="xxx"></a>标签，会导致定位标记无法跳转

作为验证，这里我在标题#### 定位标记同一行后面添加了一个<a id="xxx"></a>，可以查看当前页面的源代码，里面有两个一模一样的<a id="xxx"></a>，下面这个指向id="xxx"的定位标记将无法跳转

xxx定位标记无法跳转

脚注

脚注使你可以添加注释和参考, 而不会使文档正文混乱. 当你创建脚注时, 会在添加脚注引用的位置出现带有链接的上标编号. 读者可以单击链接以跳至页面底部的脚注内容.

要创建脚注引用, 请在方括号中添加插入符号和标识符 ([^1]). 标识符可以是数字或单词, 但不能包含空格或制表符. 标识符仅将脚注引用与脚注本身相关联 - 在脚注输出中, 脚注按顺序编号.

在中括号内使用插入符号和数字以及用冒号和文本来添加脚注内容 ([^1]：这是一段脚注). 你不一定要在文档末尾添加脚注. 可以将它们放在除列表, 引用和表格等元素之外的任何位置.

1
2
3
4
5

这是一个数字脚注[^1].
这是一个带标签的脚注[^label]

[^1]: 这是一个数字脚注
[^label]: 这是一个带标签的脚注

这是一个数字脚注1.

这是一个带标签的脚注2

图片

图片的语法与链接相似, 但包含一个在前面的感叹号.括号里也可以是本地路径，但是路径里名字不能包含空格.

1

![Minion](https://octodex.github.com/images/minion.png)

https://octodex.github.com/images/minion.png

Shortcodes

figure

1

{{< figure src="/images/lighthouse.jpg" title="" >}}

图片保存于static\images目录下，另外可以添加height，width参数，显示效果：

highlight

参见highlight

style

Hugo extended 版本对于 style shortcode 是必需的. style shortcode 用来在你的文章中插入自定义样式.

style shortcode 有两个位置参数.

第一个参数是自定义样式的内容. 它支持 SASS 中的嵌套语法, 并且 & 指代这个父元素.

第二个参数是包裹你要更改样式的内容的 HTML 标签, 默认值是 div.

1
2
3

{{< style "text-align:right; strong{color:#00b1ff;}" >}}
This is a **right-aligned** paragraph.
{{< /style >}}

效果如下：

This is a right-aligned paragraph.

admonition

admonition shortcode 支持 12 种 帮助在页面中插入提示的横幅.包括有note(默认),abstract,info,tip,success,question,warning,failure,danger,bug,example,quote.

注意
一个 注意 横幅
摘要
一个 摘要 横幅
信息
一个 信息 横幅
技巧
一个 技巧 横幅
成功
一个 成功 横幅
问题
一个 问题 横幅
警告
一个 警告 横幅
失败
一个 失败 横幅
危险
一个 危险 横幅
Bug
一个 Bug 横幅
示例
一个 示例 横幅
引用
一个 引用 横幅

支持 Markdown 或者 HTML 格式.

1
2
3
4
5
6
7

{{< admonition type=tip title="This is a tip" open=true >}}
一个 **技巧** 横幅
{{< /admonition >}}
或者
{{< admonition tip "This is a tip" true >}}
一个 **技巧** 横幅
{{< /admonition >}}

显示效果：

This is a tip
一个 技巧 横幅

  1. 这是一个数字脚注 ↩︎

  2. 这是一个带标签的脚注 ↩︎

更新于 2022-12-08
 Markdown, shortcodes
返回 | 主页