概述

Mkdocs的进阶应用主要包含两个类型:

  • 额外的功能或配置似的编辑效率或者功能拓展得到提升;
  • 基于使用方式和流程的优化

至于使用方式和流程这一类纯粹属于个人习惯和经验,所以随着使用时间的延长,必然会有更多新的心得.所有人也都可能根据自己的使用方式发掘出新的经验.


插件

总的来说,这里的插件并不是对Mkdocs本身的插件,而是对Markdown解析方式的增强.提供了一些除了常用方式外其他的表达式来实现额外的效果.

这里我们应用到的是PyMdown Extensions插件合集.当然,在详细看过文档之后其实常用的也就那么几个.

安装插件

安装插件的方式非常简单,只需要在终端或者命令行中输入:

pip install pymdown-extensions

即可自动完成安装了.

如果尚未安装python和pip可以通过Mkdocs基础教程学习和配置前置工作.

配置插件

在完成了插件安装之后,便已经具备了所有插件的能力,不过默认并没有打开,想要使用某一个插件时需要手动在mkdocs.yml文件中进行配置.如果我们希望打开插件库中一个叫做markdetails的插件,那么需要在配置文件中加入如下代码:

markdown_extensions:
    - pymdownx.details
    - pymdownx.mark

每个启用的插件名字占用一行,每行以-开头即可.详细的文档在上文的链接中可以查看,此处不再做过多展开,只是列一下我个人最长应用的几个功能.


Critic插件

这是个能够在保持文件原有样子的情况下进行修改的插件,对文本编辑有很大的帮助.想要启动该插件需要在mkdocs.yml文件中加入以下配置:

markdown_extensions:
    - pymdownx.critic:
        mode: accept 

其中,mode代表的是Critic的显示模式,共分为三种:

  • view:查看带有css标注的修改;
  • reject:放弃所有修改,仅显示原文;
  • accept:显示应用所有修改后的文本.

md内容

由于插件原因,不管底层是怎么考虑的了,即便通过代码块标记把所有的内容包起来依然不会作为代码处理.在页面上展现的会是处理过后的样子.所以把我究竟写了什么截图放上来:

简要说明

  • 添加内容: 在一对大括号{}内用++把文字内容包裹起来,如上图示例两字所示;
  • 删除内容: 将添加内容的++换成--即可,如上图乱七八糟的所示;
  • 替换内容: 在一对大括号{}内用~~把两段文字内容包裹起来,并用~>分割两段文字,既可用第二段文字在相同位置替换第一段文字,如上图着吧~>看看效果所示.
  • 高亮内容: 在一对大括号{}内用==把内容包裹起来,如上图虽然什么都看不出来所示.
  • 添加批注: 在一对打括号{}内用>><<将内容包裹起来,如上图但这是因为修改效果都直接应用了所示.

以上符号操作中间均没有空格

view模式显示效果如下

这是一段示例文字.随便写点什么乱七八糟的,然后就这么着吧看看效果. 虽然什么都看不出来 但这是因为修改效果都直接应用了

  • 删除一个列表
  • 删除一个列表

如果是整段删除,那么就会有个红色的背景

  • 添加一个列表
  • 添加一个列表

如果是整段添加,那么就会有个绿色的背景

由于不能同时演示三种效果,所以将另外两种模式的效果截图附在文稿内,


accept模式显示效果:

view


reject模式显示效果:

reject

其他配置

对于critic的view模式需要一个额外的css文件进行支持,否则无法显示如图的样式效果.虽然官方文档提供了一个css文件,但是实际应用后发现并不生效,所以我在原有文件的基础上做了些许更改.新的css文件如下.

/* Critic Markup */
.critic {
  font-family: inherit;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
  border-style: solid;
  border-width: 1px;
  padding-top: 0.1em;
  padding-bottom: 0.1em;
  text-decoration: none;
}

.critic:before,
.critic:after {
  content: '\00a0';
/*  content: ' ';*/
  padding-top: 0.1em;
  padding-bottom: 0.1em;
  font-size: initial;
}

.block:before,
.block:after {
  content: '';
}


mark.critic {
  border-color: #ff600;
  background: #FFBA61;
}

ins.critic {
  border-color: #00bb00;
  background: #ddffdd;
}

del.critic {
  border-color: #dd0000;
  background: #ffdddd;
}

 ins.break,
 del.break {
  font-size: 0;
  border: none;
}

 ins.break:before,
 del.break:before {
  content: '\00a0\b6\00a0';
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
}

 ins.after,
 del.after {
  content: '';
}

 ins.break:before {
  color: #00bb00;
  border: 1px solid #00bb00;
  background: #ddffdd;
}

 del.break:before {
  color: #bb0000;
  border: 1px solid #bb0000;
  background: #ffdddd;
}

 span.critic {
  background: #ddddff;
  border: 0;
  border-top: 1px solid #0000bb;
  border-bottom: 1px solid #0000bb;
}

 span.critic:before,
 span.critic:after {
  font-size: inherit;
  background: #ddddff;
  border: 1px solid #0000bb;
}

 span.critic:before {
/*  content: '\00a0\bb';*/
  content: '\329F\3010';
  border-right: none;
  -webkit-border-top-left-radius: 3px;
  -moz-border-top-left-radius: 3px;
  border-top-left-radius: 3px;
  -webkit-border-bottom-left-radius: 3px;
  -moz-border-bottom-left-radius: 3px;
  border-bottom-left-radius: 3px;
}

 span.critic:after {
/*  content: '\ab\00a0';*/
  content: '\3011';
  border-left: none;
  -webkit-border-top-right-radius: 3px;
  -moz-border-top-right-radius: 3px;
  border-top-right-radius: 3px;
  -webkit-border-bottom-right-radius: 3px;
  -moz-border-bottom-right-radius: 3px;
  border-bottom-right-radius: 3px;
}

 .block {
  display: block;
  padding: .02em;
}

docs文件夹下新建一个css文件夹,在css文件夹内新建一个css文件,然后把上面的代码复制进去,最后在mkdocs.yml文件中添加一段代码:

extra_css:
    - css/critic_markup.css

主要是在注释标记上添加了更佳醒目的括号和一个带圆圈的字,用到的是Unicode字符,当然也可以根据自身喜好替换成别的字符或者添加别的内容.

关于Unicode字符查询链接


Details插件

一个可以快速制作点击展开 / 折叠效果的插件.启用后在md文件中输入以下格式的文本:

默认折叠效果

??? "点击这段文字"
    这里是隐藏的内容.点击标题即可展开.

便可以方便的获得如下效果:

点击这段文字

这里是隐藏的内容.点击标题即可展开.


默认展开效果

???后添加一个加号,即???+便可以使内容默认展开,示例:

???+ "点击文字可以折叠"
    这里是默认显示的内容,但可以通过点击标题进行折叠.
点击文字可以折叠

这里是默认显示的内容,但可以通过点击标题进行折叠.


自带样式

通过在???或者???+之后添加一个样式字符串便可以给折叠块添加一个视觉效果,例如

???+ note "这是note效果的展开折叠块"
    块里的内容短是短了点,可是...谁在乎呢~
这是note效果的展开折叠块

块里的内容短是短了点,可是...谁在乎呢~

可用的样式字符串除了note之外,还包括:

  • danger: 严重危险样式
  • success: 操作成功样式
  • warning: 警告样式

具体显示效果与所使用的主题和浏览器有关,这里不再做具体演示.

其他配置

Details插件也需要额外的css文件,配置方法跟Critic一样,同样在官方提供的css文件基础上做了些许更改.调整了标题和内容的缩进,修改了默认的图标,填了个基础背景色和焦点背景色.比较随意,也可以根据自己需要进行更改.

details {
  display: block;
}

/*开启状态下标题前边的文字,此处默认为三角箭头*/
details[open] > summary::before {
/*  content: "\25BC";*/
    content: "\261F";
}

details summary {
    display: block;
    cursor: pointer;
    padding-top: 4px;
    padding-bottom: 2px;
/*    标题栏背景色*/
    background: #E9FFA6;
/*    标题栏文字加粗*/
    font-family: bold;
}

details p{
    padding-left: 2em;
/*    内容背景色*/
    background-color: #E9FFA6;   
}

details summary:focus {
  outline: none;
/*    焦点背景色*/
  background-color: #42CDFF;
}

/*合起状态下的标题左侧图标,此处默认为箭头*/
details summary::before {
/*  content: "\25B6";*/
/*  图标到左边框的距离*/
  padding-left: 1em;
  content: "\261E";
/*图标到标题的间距*/
  padding-right: 1em;
}

details summary::-webkit-details-marker {
  display: none;
}

/* Attach the "no-details" class to details tags
   in browsers that do not support them to get
   open/show functionality. */
details.no-details:not([open]) > * {
  display: none;
}

details.no-details:not([open]) summary {
  display: block;
}

Mark插件

一个很简单的插件,开启后通过用==包裹一段文字便可使其高亮显示.

这是一段 ==示例代码==.

所呈现的效果便是:

这是一段 示例代码.


SmartSymbols插件

会用到的地方并不是特别多,不过真用到的时候没有他确实头疼.通过- pymdownx.smartsymbols开启插件.

可以通过几个简单的字符插入特定的符号,如通过输入(tm)即可插入符号™.

这里提供一张支持的符号截图:

考虑到日后也有可能更新,附上原文链接以便查看详情.


Tasklist插件

一个任务清单管理插件,不过用这种方式管理任务的可能性并不大,聊胜于无吧.通过- pymdownx.tasklist开启插件.任务清单的编辑格式:

- [X] item 1
    * [X] item A
    * [ ] item B
        more text
        + [x] item a
        + [x] item b
        + [x] item c
    * [X] item C
- [ ] item 2
- [ ] item 3

显示效果:

  • item 1
    • item A
    • item B more text
      • item a
      • item b
      • item c
    • item C
  • item 2
  • item 3

个人经验

随便说两条,随着用随着加吧.

个人事务管理

其实能够应用于个人事务管理的软件太多了,不一定非要用这个东西来做.可是每次开个别的软件总会有种跳出工作状态的感觉,而且使用习惯和自定义方式都有些差强人意,这个这里好点,那个那里好点,没一个正经满意的.

所以看到Mkdocs之后立马就想到了这个办法,说起来也很简单:

  1. docs目录下新建一个文件夹即可,比方说task;
  2. mkdocs.yml文件中给nav标签添加一套任务导航页

    nav:
        - "待执行": 
            - "任务1": "task/one.md"
            - "任务2": "task/two.md"
        - "进行中":
            - "任务3": "task/three.md"
            - "任务4": "task/four.md"
    

    如果想的话其实还可以加上已完成,又或者需要分配给别人的任务,又或者购物清单,阅读列表等等任何需要的分类.

  3. 每当有件事要做,在这个文件夹中写个md,然后配置一下mkdocs.yml文件就好了.

其实这么做并不一定就比别的方式简单,但是好处在于md本身没有软件限制,任何编辑器都可以直接写,其次在于每个md代表一个独立的事儿,很容易就可以通过md把这件事详细的描述清楚,即便当时不能马上开始做,也可以在日后开始实施的时候不至于忘记了之前的思路.

而最关键的是当需要其他人来进行任务分工或者帮忙的时候,只要把特定的md文件发给对方便可以了.时至今日即便是信息化技能再差的人,收发一个文本文件的能力也还是有的.

当然,习惯这东西根据个人喜好,找到一个适合自己,并且能够有助于提升专注力和效率的方式,坚持,坚持,坚持就好了.