写作帮助文档

发表于 更新于 分类于 本文字数： 9.4k 阅读时长 ≈ 17 分钟

前言：

写作帮助文档是一种为写作过程提供指导和支持的文档。它旨在帮助作者更好地组织思维、表达观点和撰写文稿。

Button

  • 用法

    1
    2
    3
    {% button url, text, icon [class], [title] %}
    或者
    {% btn url, text, icon [class], [title] %}
    • url : URL 的绝对或相对路径。
    • text ：按钮文本。如果未指定图标，则为必填项。
    • icon ：Font Awesome 图标名称。如果未指定文本，则为必填项。
    • [class]：可选参数。Font Awesome 类：fa-fw | fa-lg | fa-2x | fa-3x | fa-4x | fa-5x
    • [title]：可选参数。鼠标悬停时的工具提示。

  • 示例

    • 拷贝基础工程 
      1
      {% btn  https://suyin-tools.lanzoui.com/i4OLlfg2qti, 拷贝基础工程, download %}
    • 苏寅 Tools 
      1
      {% btn  https://suyin-tools.cn/, 苏寅 Tools, toolbox %}
    • 苏寅 Blog 
      1
      {% btn  https://suyin-blog.cn/, 苏寅 Tools, blog %}
    • 好书推荐 
      1
      {% btn  https://suyin-blog.cn/, 好书推荐, book %}

Group Pictures

  • 用法

    1
    2
    3
    4
    5
    {% grouppicture [number]-[layout] %}
    {% endgrouppicture %}
    或者
    {% gp [number]-[layout] %}
    {% endgp %}
    • [number]：可选参数。要添加到组图片中的图片总数。
    • [layout]：可选参数。布局的索引，可以根据下图获取。
    • 建议在启用Fancybox的情况下使用集体图片。

  • 示例

    1
    2
    3
    4
    5
    {% grouppicture 3-3 %}
    ![](/images/next.svg)
    ![](/images/next.svg)
    ![](/images/next.svg)
    {% endgrouppicture %}

Label

  • 用法

    1
    {% label [class]@text %}

    • [class]：可选参数，分两种模式：

      模式 支持的值 效果
      徽章模式（色块） default | primary | accent | success | info | warning | danger 彩色圆角底块。外观（label-scheme）与色板（label-palette）由两个构建期开关决定，见 Hexo-NexT 主题安装并配置教程 · 自定义内容
      文字模式（仅文字变色） 在上述类型名前加 text- 前缀：text-default | text-primary | text-accent | text-success | text-info | text-warning | text-danger；裸写 text- 为中性（跟随正文颜色） 无背景色，只改变文字颜色，字号与正文一致

      不指定或取值无法识别时（如 {% label @text %}），使用 inverse 兜底色（soft 方案下是淡底，solid 方案下是实底），不再是浏览器 <mark> 默认黄底。inverse 在深色模式下会按 Bootstrap 的语义反转成"近白底 + 墨字"，所以浅色是深灰块、深色是白块，两种模式下文字都清晰。

    • text：@text 可以指定有或没有空格，例如 success @text 与 success@text 是相同的；文字模式同理（text-primary @text）。

  • 用法示例

    徽章模式 代码示例
    Default {% label @Default %}
    Default {% label default@Default %}
    Primary {% label primary@Primary %}
    Accent {% label accent@Accent %}
    Success {% label success@Success %}
    Info {% label info@Info %}
    Warning {% label warning@Warning %}
    Danger {% label danger@Danger %}
    文字模式（仅文字变色）
    Neutral {% label text-@Neutral %}
    Default {% label text-default@Default %}
    Primary {% label text-primary@Primary %}
    Accent {% label text-accent@Accent %}
    Success {% label text-success@Success %}
    Info {% label text-info@Info %}
    Warning {% label text-warning@Warning %}
    Danger {% label text-danger@Danger %}
    原生高亮（非 label 标签）
    esse <mark>esse</mark> 或 ==esse==
    下划线（非 label 标签）
    Underline <u>Underline</u>

  • 展示示例

    • 徽章模式1

      臣亮言：先帝创业未半而中道崩殂，今天下三分，益州疲弊，此诚危急存亡之秋也。然侍卫之臣不懈于内，忠志之士忘身于外者，盖追先帝之殊遇，欲报之于陛下也。诚宜开张圣听，以光先帝遗德，恢弘志士之气，不宜妄自菲薄，引喻失义，以塞忠谏之路也。

      宫中府中，俱为一体，陟罚臧否，不宜异同。若有作奸、犯科及为忠善者，宜付有司论其刑赏，以昭陛下平明之理，不宜偏私，使内外异法也。

    • 文字模式

      臣亮言：先帝创业未半而中道崩殂，今天下三分，益州疲弊，此诚危急存亡之秋也。然侍卫之臣不懈于内，忠志之士忘身于外者，盖追先帝之殊遇，欲报之于陛下也。诚宜开张圣听，以光先帝遗德，恢弘志士之气，不宜妄自菲薄，引喻失义，以塞忠谏之路也。

      宫中府中，俱为一体，陟罚臧否，不宜异同。若有作奸、犯科及为忠善者，宜付有司论其刑赏，以昭陛下平明之理，不宜偏私，使内外异法也。

    • 徽章模式2

      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

      Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

      Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    • 原生 mark 高亮

      臣亮言：先帝创业未半而中道崩殂，今天下三分，益州疲弊，此诚危急存亡之秋也。然侍卫之臣不懈于内，忠志之士忘身于外者，盖追先帝之殊遇，欲报之于陛下也。宫中府中，俱为一体，若有作奸、犯科及为忠善者，宜付有司论其刑赏。多行情况也会被逐段切开：先帝创业未半而中道崩殂，今天下三分，益州疲弊，此诚危急存亡之秋也。

  • 原生 mark 高亮说明

    • 正文里直接写 <mark>文字</mark> 即可，无需标签插件。样式是淡黄底 + 2px 琥珀色下沿实线 + 3px 圆角，比浏览器默认的整块黄底透气，多行换行时由 box-decoration-break: clone 逐段复制底色与下划线。
    • 徽章（{% label %}）和搜索页命中词不会被这条规则影响，可以和徽章混用，不必担心串色。
    • 徽章外观开关、色板令牌、暗色取值与完整样式实现见 Label 徽章 / 文字模式 / mark 高亮。

ans / qans

  • 简介

    自定义标签插件，用于填空、判断、选择、问答题的「默认隐藏答案」。样式、标签与交互的实现记录在 试题答案隐藏 / 显示。

  • 交互规则

    • 默认隐藏：文章内所有答案默认隐藏——填空显示为空白下划线，判断 / 选择（括号内答案）自动识别并显示为空心方框，问答题显示「点击查看答案」按钮。
    • 点击单个答案：隐藏模式下点击某处答案的空白处显示该处答案（再点收起）；填空题一题多空时，点哪个空显示哪个空。
    • 全局开关：文章页正文顶部有「显示全部答案 / 隐藏全部答案」按钮，一键切换全部答案，状态记忆在 localStorage。全局显示模式下仍可点击某个答案将其单独隐藏（再点恢复）；问答题保留「收起答案」按钮，点击按钮或直接点击答案块都能单独收起该题（再点「点击查看答案」恢复）。每次切换全局开关会清空所有单独隐藏 / 显示状态。
    • 无 JS 兜底：禁用 JS 或在 RSS / 打印等场景下，答案保持可见，不会出现空白。

  • 行内答案（填空 / 判断 / 选择）

    • 用 {% ans "答案" %} 即可（答案不含空格时引号可省略，但建议统一加引号）：
      1
      2
      3
      三相电机烧毁常见原因有：缺相、{% ans "过载" %}、{% ans "相间短路" %}。
      匝间短路指电机不同两相绕组之间发生短路。（{% ans "×" %}）
      特殊作业前必须对作业场所气体进行的核心操作是（{% ans "B" %}）。
    • 展示效果（点击空白处可显示对应答案）：
      • 三相电机烧毁常见原因有：缺相、过载、相间短路。
      • 匝间短路指电机不同两相绕组之间发生短路。（×）
      • 特殊作业前必须对作业场所气体进行的核心操作是（B）。
    • 提示：
      • <u> 标签仅作普通下划线 / 重点展示，不再用于填空题；
      • 旧写法 <span class="q-ans">答案</span> 仍然兼容，但新文章建议统一用 {% ans %}；
      • 判断 / 选择题只需把 {% ans %} 写在括号里，如 （{% ans "√" %}），页面会自动识别为空心方框样式。

  • 块级答案（问答题）

    • 用 {% qans %} ... {% endqans %} 包裹整段答案，内部支持 Markdown（列表、代码块等）。写法有两种，区别在缩进对齐：
    • 缩进写法（推荐）：{% qans %} 与题干文字同缩进，渲染进对应列表项内部，天然继承所在层级缩进——题干在多级列表的任何层级都能正确对齐，且不截断题目编号：
      1
      2
      3
      4
      5
      6
      7
      ## 简述电机过载烧机的主要原因。（30 分）

        {% qans %}
          1. 电机长时间超过额定电流运行；
          2. 频繁启动、制动；
          3. 接线错误，三角形接法电机接成星形；
        {% endqans %}
    • 顶格写法：{% qans %} 写在行首，答案块脱离列表成为正文顶层元素。样式已为它补 1.5em 缩进，仅能与一级列表的题干对齐；题干在二级及更深列表时会错位，且会截断列表编号（后续题目重新从 <ol start="n"> 编号，视觉上连续但 DOM 已拆分）。
    • 展示效果（点击「点击查看答案」展开）：
      1. 电机长时间超过额定电流运行；
      2. 频繁启动、制动；
      3. 接线错误，三角形接法电机接成星形。
    • 注意：
      • {% qans %} 内部不建议放 # 标题，避免目录（TOC）把隐藏答案的标题也列出来；
      • 多级列表场景一律用缩进写法，顶格写法只适合题干全在一级列表的试卷。

  • 参考

    • 交互设计参考 Butterfly 主题的 Tag-hide（hideInline / hideBlock），并扩展为「全局开关 + 点击单题」两级显示方式。

  • 用法

    1
    2
    3
    4
    5
    6
    {% linkgrid [image] [delimiter] [comment] %}
    {% endlinkgrid %}
    或者
    {% lg [image] [delimiter] [comment] %}
    {% endlg %}

    • [image] ：可选参数。默认图像 URL。
    • [delimiter]：可选参数。如果给出了可选的 delimiter 参数，它将被解释为每行中项目的分隔符。
    • [comment] ：可选参数。如果给出了可选的注释参数，它将被解释为注释掉一行的符号。

  • 示例

    1
    2
    3
    4
    5
    6
    7
    {% linkgrid %}
    Theme NexT | https://theme-next.js.org/ | Stay Simple. Stay NexT. | /images/apple-touch-icon-next.png
    Theme NexT | https://theme-next.js.org/ | Stay Simple. Stay NexT. | /images/apple-touch-icon-next.png
    Theme NexT | https://theme-next.js.org/ | Stay Simple. Stay NexT. | /images/apple-touch-icon-next.png
    Theme NexT | https://theme-next.js.org/ | Stay Simple. Stay NexT. | /images/apple-touch-icon-next.png
    % Theme NexT | https://theme-next.js.org/ | Stay Simple. Stay NexT. | /images/apple-touch-icon-next.png
    {% endlinkgrid %}

Mermaid

  • 设置

    • NexT config file

      1
      2
      3
      4
      5
      6
      7
      # Mermaid tag
      mermaid:
        enable: true
        # Available themes: default | dark | forest | neutral
        theme:
          light: default
          dark: dark

    • Hexo config file

      1
      2
      3
      highlight:
        exclude_languages:
          - mermaid

  • 用法

    1
    2
    3
    4
    5
    6
    7
    {% mermaid type %}
    {% endmermaid %}
    或者
    ```mermaid
    type

    ```

  • 示例

    1
    2
    3
    4
    5
    6
    7
    ```mermaid
    graph TD
    A[Hard] -->|Text| B(Round)
    B --> C{Decision}
    C -->|One| D[Result 1]
    C -->|Two| E[Result 2]
    ```
    
graph TD
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]


    1
    2
    3
    4
    5
    {% mermaid pie %}
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
    {% endmermaid %}
    
pie
"Dogs" : 386
"Cats" : 85
"Rats" : 15

Note

  • 设置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    note:
      # Note tag style values:
      #  - simple    bs-callout old alert style. Default.
      #  - modern    bs-callout new (v2-v3) alert style.
      #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
      #  - disabled  disable all CSS styles import of note tag.
      style: simple
      icons: false
      # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
      # Offset also applied to label tag variables. This option can work with disabled note tag.
      light_bg_offset: 0

  • 用法

    1
    2
    3
    {% note [class] [no-icon] [summary] %}
    Any content (support inline tags too).
    {% endnote %}
    • [class] ：可选参数。支持的值：default | primary | success | info | warning | danger。
    • [no-icon]：可选参数。禁用注释中的图标。
    • [summary]：可选参数。可选的注释摘要。

  • 示例

    Default Header

    Welcome to Hexo!

    1
    2
    3
    4
    {% note default %}
    #### Default Header
    Welcome to [Hexo!](https://hexo.io)
    {% endnote %}

    Primary Header

    Welcome to Hexo!

    1
    2
    3
    4
    {% note primary %}
    #### Primary Header
    **Welcome** to [Hexo!](https://hexo.io)
    {% endnote %}

    Info Header

    Welcome to Hexo!

    1
    2
    3
    4
    {% note info %}
    #### Info Header
    **Welcome** to [Hexo!](https://hexo.io)
    {% endnote %}

    Success Header

    Welcome to Hexo!

    1
    2
    3
    4
    {% note success %}
    #### Success Header
    **Welcome** to [Hexo!](https://hexo.io)
    {% endnote %}

    Warning Header

    Welcome to Hexo!

    1
    2
    3
    4
    {% note warning %}
    #### Warning Header
    **Welcome** to [Hexo!](https://hexo.io)
    {% endnote %}

    Danger Header

    Welcome to Hexo!

    1
    2
    3
    4
    {% note danger %}
    #### Danger Header
    **Welcome** to [Hexo!](https://hexo.io)
    {% endnote %}

PDF

  • 设置

    • NexT config file

      1
      2
      3
      4
      pdf:
        enable: true
        # Default height
        height: 500px

  • 用法

    1
    {% pdf url [height] %}
    • url ：PDF 文件的 URL（绝对路径）。
    • [height]：可选参数。PDF显示元素的高度，例如800px。
    • pdf.js 或 pdf 文件的加载可能会被 CORS 策略阻止。如果要从其他网站加载资源，请确保正确设置 Access-Control-Allow-Origin 标头。另请参见访问控制允许来源 - HTTP | MDN。

  • 示例

    1
    2
    {% pdf https://example.com/sample.pdf %}
    {% pdf /path/to/your/file.pdf 600px %}

Tabs

  • 设置

    • NexT config file

      1
      2
      3
      4
      5
      6
      tabs:
        # Make the nav bar of tabs with long content stick to the top.
        sticky: false
        transition:
          tabs: false
          labels: true

  • 用法

    1
    2
    3
    4
    5
    {% tabs Unique name, [index] %}
    <!-- tab [Tab caption] [@icon] -->
    Any content (support inline tags too).
    <!-- endtab -->
    {% endtabs %}
    • Unique name ：
      • 选项卡块标记的唯一名称，不带逗号。
      • 将在 #id 中用作每个选项卡及其索引号的前缀。
      • 如果名称中有空格，则生成 #id 时所有空格都将替换为破折号。
      • 仅对于帖子/页面的当前 url 必须是唯一的！
    • [index] ：
      • 活动选项卡的索引号。
      • 如果未指定，将选择第一个选项卡 (1)。
      • 如果索引为-1，则不会选择任何选项卡。这会有点像剧透。
      • 可选参数。
    • [Tab caption]：
      • 当前选项卡的标题。
      • 如果未指定标题，则带有选项卡索引后缀的唯一名称将用作选项卡的标题。
      • 如果未指定标题，而是指定了图标，则标题将为空。
      • 可选参数。
    • [@icon] ：
      • Font Awesome 图标名称。
      • 可以指定有或没有空格；例如“选项卡标题@icon”与“选项卡标题@icon”相同。
      • 可选参数。

  • 示例

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {% tabs Fourth unique name %}
    <!-- tab Solution 1 -->
    **This is Tab 1.**
    <!-- endtab -->

    <!-- tab Solution 2 -->
    **This is Tab 2.**
    <!-- endtab -->

    <!-- tab Solution 3 -->
    **This is Tab 3.**
    <!-- endtab -->
    {% endtabs %}

    This is Tab 1.

    This is Tab 2.

    This is Tab 3.

Video

  • 用法

    1
    {% video url %}

  • 示例

    1
    2
    {% video https://example.com/sample.mp4 %}
    {% video /path/to/your/video.mp4 %}
本文结束 感谢您的阅读
正在加载今日诗词....