Hexo-admonition-new 插件安装使用指南

English | 简体中文

Hexo-admonition-new 插件安装使用指南

简介

Hexo 内容辅助插件，支持将类似 reStructuredText 的警告提示块添加到 Markdown 文档中。支持多种提示类型（note、warning、error 等），并提供折叠功能、嵌套支持和夜间模式。效果如图：

本插件源于 hexo-admonition 迭代更新，完善了部分内容

开发这个插件的动机，是想让 hexo 与 Material for MkDocs 的提示信息兼容，让系列文章在基于 MkDocs 搭建的子站中有更好的阅读体验。

安装说明

安装插件

npm install hexo-admonition-new --save

样式配置

将提供的 CSS 文件放入主题的自定义样式文件夹（如 Blog/source/css），并在 </head> 标签之前引入：

<link rel="stylesheet" href="/css/admonition.css">

可自定义配置 CSS 文件，请参考自定义配置。

使用指南

基础语法

Hexo-admonition-new 遵循一种简单的语法：每个块都以 !!! 开头，然后是代表提示类型的关键字（type）及标题（"title"）。

!!! info "自定义标题"
    这是基于 hexo-admonition-new 插件渲染的一条提示信息。类型为 info，并设置了自定义标题。
    支持多行内容。

注意：提示内容需要缩进 4 个空格或 1 个制表符，换行行首不留空后自动结束提示块。

在 Hexo 渲染前，将被转换成如下内容：

<div class="admonition info">
  <p class="admonition-title">
    <span class="mdi mdi-information-outline admonition-icon"></span>
    "自定义标题"
  </p>
  <div class="admonition-content">
    <p>
      "这是基于 hexo-admonition-new 插件渲染的一条提示信息。类型为 info，并设置了自定义标题。"
      <br>
      "支持多行内容。"
    </p>
  </div>
</div>

折叠功能

可折叠且默认展开

以 !!!+ 开头

!!!+ warning "点击可折叠"
    这个提示块默认展开，可以点击标题折叠它。
    适合包含重要但可选的补充信息。

可折叠且默认折叠

以 !!!- 开头

!!!- warning "点击展开查看警告"
    这个警告块默认折叠，需要点击才能看到内容。
    适合包含详细的技术细节或不常用的信息。

支持的类型

提示类型 type 将用作 CSS 类名称，暂支持如下类型：

anote 不使用 "note" 为防止受 CSS 样式影响
info, todo
warning, attention, caution
error, failure, missing, fail, danger, bug
success
tip
question
example
quote

各类型样式效果可参考：https://s2.loli.net/2025/08/17/po7nrv1CyJlhG8q.png

自定义标题

使用默认标题

标题 title 是可选的，当未设置时，将以 type 作为默认值:

!!! warning
    这是一条采用默认标题的警告信息。

自定义标题

!!! warning "小心！"
    这是自定义标题的警告信息。

隐藏标题

如果不想显示标题，可以将 title 设置为 ""：

!!! warning ""
    这是不带标题的警告信息。

隐藏正文

!!! warning "这是只有标题的提示信息"

嵌套支持

支持嵌套多层和引用以及代码块等，由首页效果图可见。

!!! warning "小心！"
    这是一个警告内容。

    > 嵌套引用内容

    - 列表项 1
    - 列表项 2

        ```js
        console.log("支持代码块");
        ```
    你好

    !!! info "内层块"
        这是内层嵌套的提示内容
            !!! danger "内层块"
                这是内层嵌套的提示内容

CSS 文件

我懒得区分 error, danger 等的图标和颜色了，可按自己喜好修改：

/* ==================== CSS 变量定义 ==================== */
:root {
  /* 基础样式变量 */
  --admonition-bg: #f9f9f9;
  --admonition-title-bg: rgba(0, 0, 0, 0.03);
  --admonition-title-hover-bg: rgba(0, 0, 0, 0.06);
  --admonition-shadow: 0 2px 4px rgba(0, 0, 0, 0.04);
  --admonition-padding: 0.6rem 1rem;
  --admonition-border-width: 0.3rem;
  --admonition-border-radius: 0.4rem;

  /* 类型颜色 - 浅色模式 */
  --color-anote: #448aff;
  --color-anote-bg: #448aff1a;
  --color-anote-text: #2962ff;

  --color-info: #00b8d4;
  --color-info-bg: rgba(0, 184, 212, 0.1);
  --color-info-text: #007c91;

  --color-warning: #ff9100;
  --color-warning-bg: rgba(255, 145, 0, 0.1);
  --color-warning-text: #c66900;

  --color-error: #ff5252;
  --color-error-bg: rgba(255, 82, 82, 0.1);
  --color-error-text: #b71c1c;

  --color-tip: #00bfa5;
  --color-tip-bg: #00bfa51a;
  --color-tip-text: #00796b;

  --color-success: #00c853;
  --color-success-bg: #00c8531a;
  --color-success-text: #2e7d32;

  --color-question: #64dd17;
  --color-question-bg: #64dd171a;
  --color-question-text: #558b2f;

  --color-example: #7c4dff;
  --color-example-bg: #7c4dff1a;
  --color-example-text: #512da8;

  --color-quote: #9e9e9e;
  --color-quote-bg: #9e9e9e1a;
  --color-quote-text: #424242;
}

/* 深色模式变量 */
[data-theme="dark"] {
  --admonition-bg: #1e1e1e;
  --admonition-title-bg: rgba(255, 255, 255, 0.05);
  --admonition-title-hover-bg: rgba(255, 255, 255, 0.08);
  --admonition-shadow: 0 2px 4px rgba(0, 0, 0, 0.4);

  --color-anote: #82b1ff;
  --color-anote-bg: #82b1ff1a;
  --color-anote-text: #bbdefb;

  --color-warning: #ffb300;
  --color-warning-bg: #ffb3001a;
  --color-warning-text: #ffe082;

  --color-error: #ef5350;
  --color-error-bg: #ef53501a;
  --color-error-text: #ff8a80;

  --color-tip: #64ffda;
  --color-tip-bg: #64ffda1a;
  --color-tip-text: #1de9b6;

  --color-success: #69f0ae;
  --color-success-bg: #69f0ae1a;
  --color-success-text: #00e676;

  --color-question: #b2ff59;
  --color-question-bg: #b2ff591a;
  --color-question-text: #aeea00;

  --color-example: #b388ff;
  --color-example-bg: #b388ff1a;
  --color-example-text: #b39ddb;

  --color-quote: #bdbdbd;
  --color-quote-bg: #bdbdbd1a;
  --color-quote-text: #eeeeee;
}

/* ==================== 基础样式 ==================== */
.admonition {
  margin: 1em 0;
  padding: 0;
  border-left: var(--admonition-border-width) solid;
  border-radius: var(--admonition-border-radius);
  background-color: var(--admonition-bg);
  box-shadow: var(--admonition-shadow);
  overflow: hidden;
  page-break-inside: avoid;
}

.admonition-title {
  display: flex;
  align-items: center;
  font-weight: 600;
  padding: 0 1rem 0.1rem 0.75rem;
  font-size: 1.05em;
  background-color: var(--admonition-title-bg);
  border-top-left-radius: var(--admonition-border-radius);
  border-top-right-radius: var(--admonition-border-radius);
  margin: 0 !important;
}

.admonition-icon {
  font-size: 1.2em;
  margin-right: 0.6rem;
  opacity: 0.85;
  margin-top: 0.1rem;
}

/* 内容区域 */
.admonition>.admonition-content {
  margin: var(--admonition-padding);
}

.admonition>*:not(.admonition-title):not(.admonition-collapsible):not(.admonition-content) {
  margin: var(--admonition-padding);
}

/* ==================== 折叠功能 ==================== */
.admonition-collapsible-wrapper {
  padding: 0;
  overflow: visible;
}

.admonition>.admonition-collapsible {
  margin: 0 !important;
  width: 100%;
}

.admonition-collapsible>summary.admonition-title {
  cursor: pointer;
  list-style: none;
  user-select: none;
  position: relative;
  transition: background-color 0.2s ease;
  padding-right: 2.5rem;
}

.admonition-collapsible>summary::-webkit-details-marker,
.admonition-collapsible>summary::marker {
  display: none;
}

.admonition-collapsible>summary.admonition-title:hover {
  background-color: var(--admonition-title-hover-bg);
}

.admonition-title-text {
  flex: 1;
}

.admonition-chevron {
  position: absolute;
  right: 0.75rem;
  font-size: 1.2em;
  transition: transform 0.25s ease;
  opacity: 0.7;
}

.admonition-collapsible[open]>summary .admonition-chevron {
  transform: rotate(180deg);
}

/* 折叠内容 */
.admonition-collapsible .admonition-content {
  padding: var(--admonition-padding);
  animation: slideDown 0.25s ease-out;
}

/* 嵌套块 */
.admonition-collapsible .admonition-content>.admonition {
  margin: 0.6rem 0;
}

.admonition-collapsible .admonition-content>.admonition:first-child {
  margin-top: 0;
}

.admonition-collapsible .admonition-content>.admonition:last-child {
  margin-bottom: 0;
}

.admonition-collapsible .admonition-content>*:not(.admonition):first-child {
  margin-top: 0 !important;
}

.admonition-collapsible .admonition-content>*:not(.admonition):last-child {
  margin-bottom: 0 !important;
}

.admonition-collapsible .admonition-content>.admonition>.admonition-content {
  margin: var(--admonition-padding);
  padding: 0;
}

@keyframes slideDown {
  from {
    opacity: 0;
    transform: translateY(-10px);
  }

  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* ==================== 类型颜色（使用变量） ==================== */

/* Note */
.admonition.anote {
  border-color: var(--color-anote);
}

.admonition.anote>.admonition-title,
.admonition.anote>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-anote-bg);
  color: var(--color-anote-text);
}

/* Info / Todo */
.admonition.info,
.admonition.todo {
  border-color: var(--color-info);
}

.admonition.info>.admonition-title,
.admonition.todo>.admonition-title,
.admonition.info>.admonition-collapsible>summary.admonition-title,
.admonition.todo>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-info-bg);
  color: var(--color-info-text);
}

/* Warning / Attention / Caution */
.admonition.warning,
.admonition.attention,
.admonition.caution {
  border-color: var(--color-warning);
}

.admonition.warning>.admonition-title,
.admonition.attention>.admonition-title,
.admonition.caution>.admonition-title,
.admonition.warning>.admonition-collapsible>summary.admonition-title,
.admonition.attention>.admonition-collapsible>summary.admonition-title,
.admonition.caution>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-warning-bg);
  color: var(--color-warning-text);
}

/* Error / Failure / Fail / Danger / Bug / Missing */
.admonition.failure,
.admonition.missing,
.admonition.fail,
.admonition.error,
.admonition.danger,
.admonition.bug {
  border-color: var(--color-error);
}

.admonition.failure>.admonition-title,
.admonition.missing>.admonition-title,
.admonition.fail>.admonition-title,
.admonition.error>.admonition-title,
.admonition.danger>.admonition-title,
.admonition.bug>.admonition-title,
.admonition.failure>.admonition-collapsible>summary.admonition-title,
.admonition.missing>.admonition-collapsible>summary.admonition-title,
.admonition.fail>.admonition-collapsible>summary.admonition-title,
.admonition.error>.admonition-collapsible>summary.admonition-title,
.admonition.danger>.admonition-collapsible>summary.admonition-title,
.admonition.bug>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-error-bg);
  color: var(--color-error-text);
}

/* Tip */
.admonition.tip {
  border-color: var(--color-tip);
}

.admonition.tip>.admonition-title,
.admonition.tip>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-tip-bg);
  color: var(--color-tip-text);
}

/* Success */
.admonition.success {
  border-color: var(--color-success);
}

.admonition.success>.admonition-title,
.admonition.success>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-success-bg);
  color: var(--color-success-text);
}

/* Question */
.admonition.question {
  border-color: var(--color-question);
}

.admonition.question>.admonition-title,
.admonition.question>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-question-bg);
  color: var(--color-question-text);
}

/* Example */
.admonition.example {
  border-color: var(--color-example);
}

.admonition.example>.admonition-title,
.admonition.example>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-example-bg);
  color: var(--color-example-text);
}

/* Quote */
.admonition.quote {
  border-color: var(--color-quote);
}

.admonition.quote>.admonition-title,
.admonition.quote>.admonition-collapsible>summary.admonition-title {
  background-color: var(--color-quote-bg);
  color: var(--color-quote-text);
}

自定义配置

修改颜色

编辑 CSS 文件中的变量：

:root {
  --color-info: #YOUR_COLOR;
  --color-info-bg: rgba(YOUR_RGB, 0.1);
  --color-info-text: #YOUR_TEXT_COLOR;
}

修改图标

已在主题的 </head> 标签之前自动注入了图标库，如需修改库，可在 index.js 文件中修改 iconLibrary 。

与 CSS 文件配合以显示图标样式，图标样式配置在插件 index.js 文件首部 ADMONITION_CONFIG，也可自行修改。

图标来自 Material Design Icons

编辑插件 JavaScript 文件中的 iconMap：

const ADMONITION_CONFIG = {
  iconMap: {
    info: 'mdi-your-icon-name',
    // ...
  }
};

添加新类型

在 JavaScript 的 iconMap 和 defaultTitles 中添加新类型
在 CSS 中添加对应的颜色样式

// JavaScript
const ADMONITION_CONFIG = {
  iconMap: {
    custom: 'mdi-star',
    // ...
  },
  defaultTitles: {
    custom: 'Custom',
    // ...
  }
};

/* CSS */
.admonition.custom {
  border-color: #YOUR_COLOR;
}
.admonition.custom > .admonition-title {
  background-color: rgba(YOUR_RGB, 0.1);
  color: #YOUR_TEXT_COLOR;
}

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
CSS.css		CSS.css
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
index.js		index.js
package.json		package.json
test.md		test.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Hexo-admonition-new 插件安装使用指南

简介

安装说明

安装插件

样式配置

使用指南

基础语法

折叠功能

可折叠且默认展开

可折叠且默认折叠

支持的类型

自定义标题

使用默认标题

自定义标题

隐藏标题

隐藏正文

嵌套支持

CSS 文件

自定义配置

修改颜色

修改图标

添加新类型

License

参考

About

Uh oh!

Releases

Packages

Languages

License

Mr-EEEeee/hexo-admonition-new

Folders and files

Latest commit

History

Repository files navigation

Hexo-admonition-new 插件安装使用指南

简介

安装说明

安装插件

样式配置

使用指南

基础语法

折叠功能

可折叠且默认展开

可折叠且默认折叠

支持的类型

自定义标题

使用默认标题

自定义标题

隐藏标题

隐藏正文

嵌套支持

CSS 文件

自定义配置

修改颜色

修改图标

添加新类型

License

参考

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages