第 10 篇:小细节 Markdown 文章自动生成目录,提升阅读体验
作者:HelloGitHub-追梦人物
文中涉及的示例代码,已同步更新到 HelloGitHub-Team 仓库
上一篇中我们使用了 Markdown 来为文章提供排版支持。Markdown 在解析内容的同时还可以自动提取整个内容的目录结构,现在我们来使用 Markdown 为文章自动生成目录。
在文中插入目录
先来回顾一下博客的 Post(文章)模型,其中 body
是我们存储 Markdown 文本的字段:
blog/models.py
from django.db import models
class Post(models.Model):
# Other fields ...
body = models.TextField()
再来回顾一下文章详情页的视图,我们在 detail
视图函数中将 post
的 body
字段中的 Markdown 文本解析成了 HTML 文本,然后传递给模板显示。
blog/views.py
def detail(request, pk):
post = get_object_or_404(Post, pk=pk)
post.body = markdown.markdown(post.body,
extensions=[
'markdown.extensions.extra',
'markdown.extensions.codehilite',
'markdown.extensions.toc',
])
return render(request, 'blog/detail.html', context={'post': post})
markdown.markdown()
方法把 post.body
中的 Markdown 文本解析成了 HTML 文本。同时我们还给该方法提供了一个 extensions
的额外参数。其中 markdown.extensions.toc
就是自动生成目录的拓展(这里可以看出我们有先见之明,如果你之前没有添加的话记得现在添加进去)。
在渲染 Markdown 文本时加入了 toc 拓展后,就可以在文中插入目录了。方法是在书写 Markdown 文本时,在你想生成目录的地方插入 [TOC]
标记即可。例如新写一篇 Markdown 博文,其 Markdown 文本内容如下:
[TOC]
## 我是标题一
这是标题一下的正文
## 我是标题二
这是标题二下的正文
### 我是标题二下的子标题
这是标题二下的子标题的正文
## 我是标题三
这是标题三下的正文
其最终解析后的效果就是:
原本 [TOC]
标记的地方被内容的目录替换了。
在页面的任何地方插入目录
上述方式的一个局限性就是只能通过 [TOC]
标记在文章内容中插入目录。如果我想在页面的其它地方,比如侧边栏插入一个目录该怎么做呢?方法其实也很简单,只需要稍微改动一下解析 Markdown 文本内容的方式即可,具体代码就像这样:
blog/views.py
def detail(request, pk):
post = get_object_or_404(Post, pk=pk)
md = markdown.Markdown(extensions=[
'markdown.extensions.extra',
'markdown.extensions.codehilite',
'markdown.extensions.toc',
])
post.body = md.convert(post.body)
post.toc = md.toc
return render(request, 'blog/detail.html', context={'post': post})
和之前的代码不同,我们没有直接用 markdown.markdown()
方法来渲染 post.body
中的内容,而是先实例化了一个 markdown.Markdown
对象 md
,和 markdown.markdown()
方法一样,也传入了 extensions
参数。接着我们便使用该实例的 convert
方法将 post.body
中的 Markdown 文本解析成 HTML 文本。而一旦调用该方法后,实例 md
就会多出一个 toc
属性,这个属性的值就是内容的目录,我们把 md.toc
的值赋给 post.toc
属性(要注意这个 post 实例本身是没有 toc 属性的,我们给它动态添加了 toc 属性,这就是 Python 动态语言的好处)。
接下来就在博客文章详情页的文章目录侧边栏渲染文章的目录吧!删掉占位用的目录内容,替换成如下代码:
{% block toc %}
<div class="widget widget-content">
<h3 class="widget-title">文章目录</h3>
{{ post.toc|safe }}
</div>
{% endblock toc %}
即使用模板变量标签 {{ post.toc }} 显示模板变量的值,注意 post.toc 实际是一段 HTML 代码,我们知道 django 会对模板中的 HTML 代码进行转义,所以要使用 safe 标签防止 django 对其转义。其最终渲染后的效果就是:
处理空目录
现在目录已经可以完美生成了,不过还有一个异常情况,当文章没有任何标题元素时,Markdown 就提取不出目录结构,post.toc 就是一个空的 div 标签,如下:
<div class="toc">...............................
<ul></ul>
</div>
对于这种没有目录结构的文章,在侧边栏显示一个目录是没有意义的,所以我们希望只有在文章存在目录结构时,才显示侧边栏的目录。那么应该怎么做呢?
分析 toc 的内容,如果有目录结构,ul 标签中就有值,否则就没有值。我们可以使用正则表达式来测试 ul 标签中是否包裹有元素来确定是否存在目录。
def detail(request, pk):
post = get_object_or_404(Post, pk=pk)
md = markdown.Markdown(extensions=[
'markdown.extensions.extra',
'markdown.extensions.codehilite',
'markdown.extensions.toc',
])
post.body = md.convert(post.body)
m = re.search(r'<div class="toc">\s*<ul>(.*)</ul>\s*</div>', md.toc, re.S)
post.toc = m.group(1) if m is not None else ''
return render(request, 'blog/detail.html', context={'post': post})
这里我们正则表达式去匹配生成的目录中包裹在 ul 标签中的内容,如果不为空,说明目录,就把 ul 标签中的值提取出来(目的是只要包含目录内容的最核心部分,多余的 HTML 标签结构丢掉)赋值给 post.toc
;否则,将 post 的 toc 置为空字符串,然后我们就可以在模板中通过判断 post.toc 是否为空,来决定是否显示侧栏目录:
{% block toc %}
{% if post.toc %}
<div class="widget widget-content">
<h3 class="widget-title">文章目录</h3>
<div class="toc">
<ul>
{{ post.toc|safe }}
</ul>
</div>
</div>
{% endif %}
{% endblock toc %}
这里我们看到了一个新的模板标签 {% if %}
,这个标签用来做条件判断,和 Python 中的 if 条件判断是类似的。
美化标题的锚点 URL
文章内容的标题被设置了锚点,点击目录中的某个标题,页面就会跳到该文章内容中标题所在的位置,这时候浏览器的 URL 显示的值可能不太美观,比如像下面的样子:
#_1
就是锚点,Markdown 在设置锚点时利用的是标题的值,由于通常我们的标题都是中文,Markdown 没法处理,所以它就忽略的标题的值,而是简单地在后面加了个 _1 这样的锚点值。为了解决这一个问题,需要修改一下传给 extentions
的参数,其具体做法如下:
blog/views.py
from django.utils.text import slugify
from markdown.extensions.toc import TocExtension
def detail(request, pk):
post = get_object_or_404(Post, pk=pk)
md = markdown.Markdown(extensions=[
'markdown.extensions.extra',
'markdown.extensions.codehilite',
# 记得在顶部引入 TocExtension 和 slugify
TocExtension(slugify=slugify),
])
post.body = md.convert(post.body)
m = re.search(r'<div class="toc">\s*<ul>(.*)</ul>\s*</div>', md.toc, re.S)
post.toc = m.group(1) if m is not None else ''
return render(request, 'blog/detail.html', context={'post': post})
和之前不同的是,extensions
中的 toc
拓展不再是字符串 markdown.extensions.toc
,而是 TocExtension
的实例。TocExtension
在实例化时其 slugify
参数可以接受一个函数,这个函数将被用于处理标题的锚点值。Markdown 内置的处理方法不能处理中文标题,所以我们使用了 django.utils.text
中的 slugify
方法,该方法可以很好地处理中文。
这时候标题的锚点 URL 变得好看多了。
欢迎关注 HelloGitHub 公众号,获取更多开源项目的资料和内容
第 10 篇:小细节 Markdown 文章自动生成目录,提升阅读体验的更多相关文章
- 懒人小工具:T4自动生成Model,Insert,Select,Delete以及导出Excel的方法
之前写了篇文章,懒人小工具:[自动生成Model,Insert,Select,Delete以及导出Excel的方法](http://www.jianshu.com/p/d5b11589174a),但是 ...
- 用jquery实现文章自动生成二级目录(续)
前文:用jquery实现文章自动生成二级目录. 使用方法的补充 我们可以把我们的js和css上传到博客园,然后在页面HTML代码中使用他们. 发现的一些问题 在我把我的js放到自己的博客园上运行之后发 ...
- Markdown自动生成目录
Markdown自动生成目录 使用npm语法生成 1.安装npm 2.安装doctoc插件 3.执行生成 参考 Markdown自动生成目录 使用npm语法生成 1.安装npm 我的系统是deepin ...
- 去除office自动生成目录后生成的小框框(内容控件,目录控件)
如何自动生成目录在这里就不进行阐述了,想必能看到这这里的人已经完成了目录的自动生成,那我就来直接演示如何去除自动生成目录后烦人的目录内容控件吧 直接上图片
- Word 2010文档自动生成目录和某页插入页码
一.Word 2010文档自动生成目录 关于Word文档自动生成目录一直是我身边同学们最为难的地方,尤其是毕业论文,经常因为目录问题,被要求修改,而且每次修改完正文后,目录的内容和页码可能都会发生变化 ...
- csdn自动生成目录索引、插入代码片快捷键
文章目录 自动生成目录索引 插入代码片 自动生成目录索引 文章开头加入 @[TOC](目录描述) 目录描述可不写 插入代码片 cmd/ctrl + shift + k
- Word自动生成目录
博主最近在写报告的时候要在Word里面做个目录,再做个页码,然后上网搜了一些方法,非常零散,我弄了好久才弄好.在这里我把整套方法分享一下. 声明:内容完全独创! 工具:Word 2016. 效果:如下 ...
- tp5自动生成目录
1.// 定义应用目录 define('APP_PATH', __DIR__ . '/../application/'); // 加载框架引导文件 require __DIR__ . '/../thi ...
- Thinkphp5.0实战开发二------自动生成目录结构
序言 ThinkPHP5.0 具备自动创建功能,可以用来自动生成需要的模块及目录结构和文件等,自动生成主要调用\think\Build 类库.ThinkPHP5.0中模块文件夹在application ...
随机推荐
- 性能测试-实例讲解VU、RPS、RT公式换算
概述 今天看到一篇文章讲解VU.RPS.RT,中间有一个公式如下图 并发数 = RPS * 响应时间 于是我在本地做了几次实验,试图验证一下公式的准确性 实验网站 www.baidu.com 第一次 ...
- bash 遍历目录
bash遍历目录脚本traverse.sh: #!/bin/bash datadir=$ declare -a dirlist dirlist=`>/dev/null` for i in ${d ...
- CF1027D Mouse Hunt题解
题目: 伯兰州立大学的医学部刚刚结束了招生活动.和以往一样,约80%的申请人都是女生并且她们中的大多数人将在未来4年(真希望如此)住在大学宿舍里. 宿舍楼里有nn个房间和一只老鼠!女孩们决定在一些房间 ...
- Netty(DotNetty)原理解析
一.背景介绍 DotNetty是微软的Azure团队,使用C#实现的Netty的版本发布.不但使用了C#和.Net平台的技术特点,并且保留了Netty原来绝大部分的编程接口.让我们在使用时,完全可以依 ...
- Java之JDBC 通过加载properties配置文件连接数据库
通常情况下,我们通过JDBC连接数据库的时候,不会将数据库相关配置写死,因为到时候数据库一有改动,就要重新打包部署到服务器或者替换相关的.class文件,这样非常不灵活.因此,咱们一般会通过读取配置文 ...
- jmeter环境变量
jmeter环境变量配置jmeter环境变量时,同时也需要配置Java变量(jdk最好使用1.7及1.7以上的版本)1.配置jdk环境变量安装jdk正常安装,一路默认就好,记住安装路径,配置环境变量时 ...
- 【数据结构】B树、B+树详解
B树 前言 首先,为什么要总结B树.B+树的知识呢?最近在学习数据库索引调优相关知识,数据库系统普遍采用B-/+Tree作为索引结构(例如mysql的InnoDB引擎使用的B+树),理解不透彻B树,则 ...
- 逆向MFC程序
目录 @ 1 MFC执行流程 1.1 环境支持 1.2 分析 1.3 实践探索 1.3.1 创建一个MFC程序 1.3.2 下关键断点并调试 1.4 转向MFC库源文件中观测 2 逆向 2.1 特征码 ...
- IrisSkin2.dll 添加皮肤
使用说明:把控件拖到你的form上,只需一行代码,即可实现整个form包括其所有控件的皮肤的更换,总共有几十套皮肤供使用,非常方便.省去你设计开发软件皮肤系统的时间和精力.全部源代码就一行: skin ...
- win10下nodejs的安装及配置
这里主要引用两篇文章,写的非常详细,也能解决你可能出现的问题 nodejs安装及配置 如何删除之前nodejs设置的 npm config set prefix .....