🦋

HelloDjango - Django博客教程（第二版）

Markdown 文章自动生成目录，提升阅读体验

2019-08-2117010 阅读20 评论

上一篇中我们使用了 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]

## 我是标题一

这是标题一下的正文

## 我是标题二

这是标题二下的正文

### 我是标题二下的子标题
这是标题二下的子标题的正文

## 我是标题三
这是标题三下的正文

其最终解析后的效果就是：

Markdown文中目录

原本 [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自动生成的侧边栏目录

处理空目录

现在目录已经可以完美生成了，不过还有一个异常情况，当文章没有任何标题元素时，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 显示的值可能不太美观，比如像下面的样子：

http://127.0.0.1:8000/posts/8/#_1

http://127.0.0.1:8000/posts/8/#_3

#_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 变得好看多了。

http://127.0.0.1:8000/posts/8/#我是标题一

http://127.0.0.1:8000/posts/8/#我是标题二下的子标题

-- EOF --

让博客支持 Markdown 语法和代码高亮 自动生成文章摘要
20 评论
登录后回复
Feko
2022-08-11 17:38:15

import re
通过+1

回复
伐里个伐
2020-11-21 16:16:46

锚点按照方法做了变成一段乱码怎么办？

回复
BigOrangeCat 伐里个伐
2021-02-24 17:47:10

我的也是，在浏览器的网址栏，中文显示为乱码。不过 当鼠标游标悬浮在标题上时，浏览器界面的最下面一行显示的是中文。。

回复
runiccolon
2020-07-03 09:35:49

图片为啥都挂了那

回复
BigOrangeCat runiccolon
2021-02-24 17:47:41

HelloDjango 第 10 篇：小细节 Markdown 文章自动生成目录，提升阅读体验 - 削微寒 - 博客园 https://www.cnblogs.com/xueweihan/p/11392355.html

回复
nonozone
2020-05-10 18:00:49

    post.body = md.convert(post.body)
        post.toc = md.toc

第二行的是不是要前进一档才可以？

回复
nonozone nonozone
2020-05-11 12:14:55

还有一个问题就是，要在最开始 import re，不然下面的正则会出错。

NameError: name 're' is not defined
回复
cymnb
2020-04-23 15:39:02

错误信息：AttributeError: 'Markdown' object has no attribute 'toc'

文章页使用markdown扩展出现错误，代码如下

def article(request, pk):
    article = get_object_or_404(Article, pk=pk)
    # 原始markdown文档解析成html，启用md语法扩展
    md = markdown.Markdown(
            extentions=[
                'markdown.extensions.extra',    # 基础扩展
                'markdown.extensions.codehilite',   # 语法高亮扩展
                'markdown.extensions.toc',  # 允许自动生成目录扩展
                # TocExtension(slugify=slugify),
            ])
    article.body = md.convert(article.body)
    # # m = re.search(r'<div class="toc">\s*<ul>(.*)</ul>\s*</div>', md.toc, re.S)
    # # article.toc = m.group(1) if m is not None else ''
    article.toc = md.toc
    context = {
        'article': article
    }
    return render(request, 'blog/article.html', context)

补充说明

Django 3.0.4
Markdown 3.2.1
也没有搜索到相关说明，能力不足未能解决，来问问

参考链接

https://github.com/mkdocs/mkdocs/issues/376
https://github.com/trapeze/python-discount/issues/1

其他问题

使用markdown方法生成的正文目录不显示，倒是没有报错。
1. 后台文章首行写入[TOC]
2. 后台预览有显示文中目录
3. 前端正文直接就显示了[TOC]而非文中目录

致谢

希望博主以及其他网友提供帮助，在此非常感谢热心博主和网友们。谢谢

回复
追梦人物 cymnb
2020-05-05 11:16:46

Markdown 可能是版本问题，参考官方文档中的说明换种方式试一试，不一定严格按照本教程的来：
https://python-markdown.github.io/extensions/toc/

回复
YAO ZELIANG
2020-04-03 04:24:21

姿瓷！讲的很好

回复
我是冰霜
2020-03-22 10:25:05

应该是这个效果
image.png

回复
张东建46337
2020-01-23 22:18:33

你好。本页面左边的目录。并不是本文章内的。像这样的目是怎么生成的？ 只是一个普通的 在内容页 循环输出 分类栏目 还是有什么方法做到的？ 谢谢

回复
追梦人物 张东建46337
2020-01-31 11:43:41

就是拿到全部文章，然后循环获取标题显示即可。

回复
好汉源6475728697
2019-10-06 16:04:08

在处理空目录时，使用到了re模块，是不是应该在前面加上import re?

回复
追梦人物 好汉源6475728697
2019-10-09 06:51:46

嗯，是的。

回复
conqueror 好汉源6475728697
2019-10-09 10:04:47

不知道你的侧边栏是什么效果,我这边侧边栏文章目录没有内容

回复
hifer conqueror
2019-11-09 10:43:19

在body里加入
[TOC]

文章一

文章二

回复
冰加可乐__ conqueror
2019-12-30 16:39:38

image.png像这样

回复
冰加可乐__ 追梦人物
2019-12-30 16:40:27

哥，为什么图片都挂了？

回复
719923505
2019-09-04 15:59:26
  1. 侧边目录到底什么效果？
回复

目录