Markdown 语法和代码高亮_生成目录

2020年1月8日 13:44 阅读 133 评论 0

为了增加用户浏览文章的便捷 修改文章界面左侧sidebar为文章目录栏。

让博客支持 Markdown 语法和代码高亮

为了让博客文章具有良好的排版,显示更加丰富的格式,我们使用 Markdown 语法来书写博文。Markdown 是一种 HTML 文本标记语言,只要遵循它约定的语法格式,Markdown 的解析工具就能够把 Markdown 文档转换为标准的 HTML 文档,从而使文章呈现更加丰富的格式,例如标题、列表、代码块等等 HTML 元素。由于 Markdown 语法简单直观,不用超过 5 分钟就可以轻松掌握常用的标记语法,因此大家青睐使用 Markdown 书写 HTML 文档。下面让我们的博客也支持使用 Markdown 写作。

安装 Python Markdown

将 Markdown 格式的文本解析成标准的 HTML 文档是一个复杂的工程,好在已有好心人帮我们完成了这些工作,直接拿来使用即可。首先安装 Markdown,这是一个 Python 第三方库,在项目根目录下运行命令

pip install markdown

在modle.py中我们增加函数。对文章makrodwn内容进行转换再返回:

# 文章
class Article(models.Model):
······
    def body_to_markdown(self):
        md_content = emoji.emojize(self.body, use_aliases=True)
        return markdown.markdown(md_content, extensions=[
            'markdown.extensions.extra',
            'markdown.extensions.codehilite',
            # 'markdown.extensions.toc',
            TocExtension(slugify=sfy),
        ])

前端中我们可以调用模板函数获取值:

<!-- 文章内容 -->
<div class=" f-17" >
    {{ article.body_to_markdown |safe }}
    <p class="font-weight-bold text-info">
        <i class="fa fa-bullhorn mx-1"></i>
        原创文章,转载请注明出处:{{ request.build_absolute_uri }}
    </p>
</div>

safe 标签 我们在发布的文章详情页没有看到预期的效果,而是类似于一堆乱码一样的 HTML 标签,这些标签本应该在浏览器显示它自身的格式,但是 django 出于安全方面的考虑,任何的 HTML 代码在 django 的模板中都会被转义(即显示原始的 HTML 代码,而不是经浏览器渲染后的格式)。为了解除转义,只需在模板变量后使用 safe 过滤器即可,告诉 django,这段文本是安全的,你什么也不用做。在模板中找到展示博客文章内容的 {{ post.body }} 部分,为其加上 safe 过滤器:{{ post.body|safe }},大功告成,这下看到预期效果了。

Markdown 测试 safe 是 django 模板系统中的过滤器(Filter),可以简单地把它看成是一种函数,其作用是作用于模板变量,将模板变量的值变为经过滤器处理过后的值。例如这里 {{ post.body|safe }},本来 {{ post.body }}经模板系统渲染后应该显示 body 本身的值,但是在后面加上 safe 过滤器后,渲染的值不再是 body 本身的值,而是由 safe 函数处理后返回的值。过滤器的用法是在模板变量后加一个 | 管道符号,再加上过滤器的名称。可以连续使用多个过滤器,例如 {{ var|filter1|filter2 }}。

代码高亮,使用js文件解析和利用github代码高亮文件

程序员写博客免不了要插入一些代码,Markdown 的语法使我们容易地书写代码块,但是目前来说,显示的代码块里的代码没有任何颜色,很不美观,也难以阅读,要是能够像代码编辑器里一样让代码高亮就好了。

代码高亮我们借助 js 插件来实现,其原理就是 js 解析整个 html 页面,然后找到代码块元素,为代码块中的元素添加样式。我们使用的插件叫做 highlight.js 和 highlightjs-line-numbers.js,前者提供基础的代码高亮,后者为代码块添加行号。

首先在 base.html 的 head 标签里引入代码高亮的样式,有多种样式供你选择,这里我们选择 Github 主题的样式。样式文件直接通过 CDN 引入,同时在 style 标签里自定义了一点元素样式,使得代码块的显示效果更加完美。

<link href="https://cdn.bootcss.com/highlight.js/9.15.8/styles/github.min.css" rel="stylesheet">
<style type="text/css">

    .codehilite {
        padding: 0;
    }

    /* for block of numbers */
    .hljs-ln-numbers {
        -webkit-touch-callout: none;
        -webkit-user-select: none;
        -khtml-user-select: none;
        -moz-user-select: none;
        -ms-user-select: none;
        user-select: none;

        text-align: center;
        color: #ccc;
        border-right: 1px solid #CCC;
        vertical-align: top;
        padding-right: 5px;
    }

    .hljs-ln-n {
        width: 30px;
    }

    /* for block of code */
    .hljs-ln .hljs-ln-code {
        padding-left: 10px;
        white-space: pre;
    }
    .markdown-body img {
        max-width: 90% !important;
        width: auto;
        height: auto;
        text-align: center;
        margin-left: auto;
        margin-right: auto;
        display: block;
        padding: 10px 0px 10px 0px;
    }
    .freen-sidebar-wrapper:first-child{
        margin-top: 60px;
    }
    .freen-menu-ul > li > ul > li a {
        padding-right: 1rem;
    }
</style>

并为文章的最顶层div增加class="markdown-body"元素,好让css文件起作用。

使用pygments代码高亮

安装:

(env) PS F:\workspace\django_blog> pip install pygments  env) PS F:\workspace\django_blog> pip install pygments

引入github对markdown进行修饰的css文件:

<link href="https://cdn.bootcss.com/github-markdown-css/3.0.1/github-markdown.min.css" rel="stylesheet">

和之前的不一样。因为我们只需要支持除代码之外的样式 可以在官网中看看pygments的使用:https://pygments.org/demo/ 使用方法进入到static/css文件夹中

pygmentize -f html -a .codehilite -S default > pygments.css

-a .highlight指所有css选择器都具有.highlight这一祖先选择器 -S default就是指定所需要的样式了,各位可以对各种样式都尝试一下。在官网上是可以直接尝试的哦! pygments.css将内容输出到pygments.css文件中

生成我们需要的css文件,并引用:

<!-- 文本区 -->
<link rel="stylesheet" href="{% static 'css/pygments.css' %}">

用这种方式我们尝试几款代码css样式。 第一种default:

第二种monokai: manokai的样式和我们上面引入的gihub的样式发生了冲突,我们需要调整以下参数:

<style type="text/css">
    .markdown-body img {
        max-width: 90% !important;
        width: auto;
        text-align: center;
        margin-left: auto;
        margin-right: auto;
        display: block;
        padding: 10px 0px 10px 0px;
    }
    .codehilite  pre{ color: #f8f8f2 }
    .codehilite .err {
        color: #f8f8f2;
        background: #272822;
    }
    .markdown-body .highlight pre, .markdown-body pre {
        background: #272822;
    }
    .freen-sidebar-wrapper:first-child{
        margin-top: 60px;
    }
    .freen-menu-ul > li > ul > li a {
        padding-right: 1rem;
    }
</style>
<!-- 文本区 -->
<link rel="stylesheet" href="{% static 'css/monokai.css' %}">

在base中添加block,方便导入目录

在base.html中修改如下:

 <!--freen sidebar -->
    {% cache 7200 'sidebar' %}
    <aside id="freen-sidebar" class="freen-sidebar">
    {% block md_toc %}
    ···html代码
    {% endblock %}
    </aside>
    {% endcache %}

在合适的地方添加md_toc模块,方便article界面进行继承。

{% block md_toc %}
文章目录
{% endblock %}

效果如下:

在model中添加函数,获取我们的目录:

    def body_to_toc(self):
        md = markdown.Markdown(extensions=[
        'markdown.extensions.extra',
        'markdown.extensions.codehilite',
        'markdown.extensions.toc',
        ])
        md.convert(self.body)
        m = re.search(r'<div class="toc">\s*<ul>(.*)</ul>\s*</div>', md.toc, re.S)
        toc = m.group(1) if m is not None else ''

        return toc

设置前端样式,让其变得更美观

{% block md_toc %}
<div id="freen-sidebar-cell" class="freen-sidebar-cell w-100">
<!-- MENU -->
<nav id="freen-main-menu" class="menu-main-menu-container freen-main-menu">
    <ul class="freen-menu-ul">
        <li><a href="#">⛳文章目录</a>
        {{ article.body_to_toc |safe }}
        </li>
    </ul>
</nav>
</div>
{% endblock %}

稍微修一下前端样式:

.freen-sidebar-wrapper:first-child{
    margin-top: 60px;
}
.freen-menu-ul > li > ul > li a {
    padding-right: 1rem;
}

大致效果如下:

slugify文章目录

文章内容的标题被设置了锚点,点击目录中的某个标题,页面就会跳到该文章内容中标题所在的位置,这时候浏览器的 URL 显示的值可能不太美观,比如像下面的样子:

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

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

#_1 就是锚点,Markdown 在设置锚点时利用的是标题的值,由于通常我们的标题都是中文,Markdown 没法处理,所以它就忽略的标题的值,而是简单地在后面加了个 _1 这样的锚点值。为了解决这一个问题,需要修改一下传给 extentions 的参数,其具体做法如下:

model.py: 记得import:

from markdown.extensions.toc import TocExtension
from django.utils.text import slugify as sfy
    def body_to_markdown(self):
        md_content = emoji.emojize(self.body, use_aliases=True)
        return markdown.markdown(md_content, extensions=[
            'markdown.extensions.extra',
            'markdown.extensions.codehilite',
            # 'markdown.extensions.toc',
            TocExtension(slugify=sfy),
        ])

    def body_to_toc(self):
        md = markdown.Markdown(extensions=[
        'markdown.extensions.extra',
        'markdown.extensions.codehilite',
        # 'markdown.extensions.toc',
        # 记得在顶部引入 TocExtension 和 slugify
        TocExtension(slugify=sfy),
        ])
        md.convert(self.body)
        m = re.search(r'<div class="toc">\s*<ul>(.*)</ul>\s*</div>', md.toc, re.S)
        toc = m.group(1) if m is not None else ''
        return toc

和之前不同的是,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/#我是标题二下的子标题

原创文章,转载请注明出处:https://boywithacoin.cn/article/markdown-yu-fa-he-dai-ma-gao-liang-sheng-cheng-mu-lu/


您尚未登录,请 登录注册 后评论
    0 人参与 | 0 条评论
    暂时没有评论,欢迎来尬聊!