9 - 支持 Markdown 语法和代码高亮
2017-05-20 11:55
459 查看
为了让博客文章具有良好的排版,显示更加丰富的格式,我们使用 Markdown 语法来书写我们的博文。Markdown 是一种 HTML 文本标记语言,只要遵循它约定的语法格式,Markdown 的渲染器就能够把我们写的文章转换为标准的 HTML 文档,从而让我们的文章呈现更加丰富的格式,例如标题、列表、代码块等等 HTML 元素。由于 Markdown 语法简单直观,不用超过 5 分钟就可以掌握常用的标记语法,因此大家青睐使用 Markdown 书写 HTML 文档。下面让我们的博客也支持使用 Markdown 书写。
这样我们在模板中展示 {{ post.body }} 的时候,就不再是原始的 Markdown 文本了,而是渲染过后的 HTML 文本。注意这里我们给
来测试一下效果,进入后台,这次我们发布一篇用 Markdown 语法写的测试文章看看,你可以使用以下的 Markdown 测试代码进行测试,也可以自己书写你喜欢的 Markdown 文本。假设你是 Markdown 新手参考一下这些教程,一定学一下,保证你可以在 5 分钟内掌握常用的语法格式,而以后对你写作受用无穷。可谓充电五分钟,通话 2 小时。以下是我学习中的一些参考资料:
Markdown——入门指南
Markdown 语法说明 (简体中文版)
如果你发现无法显示代码块,即代码无法换行,请检查代码块的语法是否书写有误。代码块的语法如上边的测试文本中最后一段所示。
你可能想在文章中插入图片,目前能做的且推荐做的是使用外链引入图片。比如将图片上传到七牛云这样的云存储服务器,然后通过 Markdown 的图片语法将图片引入。Markdown 引入图片的语法为:
safe 是 Django 模板系统中的过滤器(Filter),可以简单地把它看成是一种函数,其作用是作用于模板变量,将模板变量的值变为经过滤器处理过后的值。例如这里 {{ post.body|safe }},本来 {{ post.body }} 经模板系统渲染后应该显示 body 本身的值,但是在后面加上 safe 过滤器后,渲染的值不再是body 本身的值,而是由 safe 函数处理后返回的值。过滤器的用法是在模板变量后加一个 | 管道符号,再加上过滤器的名称。可以连续使用多个过滤器,例如 {{ var|filter1|filter2 }}。
![](http://opsbzmsv1.bkt.clouddn.com/Markdown%20%E6%B5%8B%E8%AF%95.png)
搞定了,虽然我们除了安装了一下 Pygments 什么也没做,但 Markdown 使用 Pygments 在后台为我们做了很多事。如果你打开博客详情页,找到一段代码段,在浏览器查看这段代码段的 HTML 源代码,可以发现 Pygments 的工作原理是把代码切分成一个个单词,然后为这些单词添加 css 样式,不同的词应用不同的样式,这样就实现了代码颜色的区分,即高亮了语法。为此,还差最后一步,引入一个样式文件来给这些被添加了样式的单词定义颜色。
这里 + 号表示添加这行代码。好了,看看效果,大功告成,终于可以愉快地贴代码了。
![](http://opsbzmsv1.bkt.clouddn.com/%E4%BB%A3%E7%A0%81%E9%AB%98%E4%BA%AE.png)
注意:如果你按照教程中的方法做完后发现代码依然没有高亮,请依次检查以下步骤:
确保在渲染文本时添加了
确保安装了 Pygments。
确保代码块的 Markdown 语法正确,特别是指明该代码块的语言类型,具体请参见上文中 Markdown 的语法示例。
在浏览器端代码块的源代码,看代码是否被 pre 标签包裹,并且代码的每一个单词都被 span 标签包裹,且有一个 class 属性值。如果没有,极有可能是前三步中某个地方出了问题。
确保用于代码高亮的样式文件被正确地引入,具体请参见上文中引入样式文件的讲解。
有些样式文件可能对代码高亮没有作用,首先尝试用 github.css 样式文件做测试。
如果遇到问题,请通过下面的方式寻求帮助。
在 支持 Markdown 语法和代码高亮 - 追梦人物的博客 的评论区留言。
将问题的详细描述通过邮件发送到 djangostudyteam@163.com,一般会在 24 小时内回复。
更多Django 教程,请访问 追梦人物的博客。
安装 Python Markdown
将 Markdown 格式的文本渲染成标准的 HTML 文档是一个复杂的工作,好在已有好心人帮我们完成了这些工作,我们直接使用即可。首先安装 Markdown,这是一个 Python 第三方库,激活虚拟环境,然后使用命令pip install markdown安装即可。
在 detail 视图中渲染 Markdown
将 Markdown 格式的文本渲染成 HTML 文本非常简单,只需调用这个库的markdown方法即可。我们书写的博客文章内容存在
Post的
body属性里,回到我们的详情页视图函数,对
post的
body的值做一下渲染,把 Markdown 文本转为 HTML 文本再传递给模板:
blog/views.py import markdown from django.shortcuts import render, get_object_or_404 from .models import Post def detail(request, pk): post = get_object_or_404(Post, pk=pk) # 记得在顶部引入 markdown 模块 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})
这样我们在模板中展示 {{ post.body }} 的时候,就不再是原始的 Markdown 文本了,而是渲染过后的 HTML 文本。注意这里我们给
markdown渲染函数传递了额外的参数
extensions,它是对 Markdown 语法的拓展,这里我们使用了三个拓展,分别是 extra、codehilite、toc。extra 本身包含很多拓展,而 codehilite 是语法高亮拓展,这为我们后面的实现代码高亮功能提供基础,而 toc 则允许我们自动生成目录(在以后会介绍)。
来测试一下效果,进入后台,这次我们发布一篇用 Markdown 语法写的测试文章看看,你可以使用以下的 Markdown 测试代码进行测试,也可以自己书写你喜欢的 Markdown 文本。假设你是 Markdown 新手参考一下这些教程,一定学一下,保证你可以在 5 分钟内掌握常用的语法格式,而以后对你写作受用无穷。可谓充电五分钟,通话 2 小时。以下是我学习中的一些参考资料:
Markdown——入门指南
Markdown 语法说明 (简体中文版)
# 一级标题 ## 二级标题 ### 三级标题 - 列表项1 - 列表项2 - 列表项3 > 这是一段引用 ```python 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 引入图片的语法为:
![图片说明](图片链接)。
safe 标签
我们在发布的文章详情页没有看到预期的效果,而是类似于一堆乱码一样的 HTML 标签,这些标签本应该在浏览器显示它本身的格式,但是 Django 出于安全方面的考虑,任何的 HTML 代码在 Django 的模板中都会被转义(即显示原始的 HTML 代码,而不是经浏览器渲染后的格式)。为了解除转义,只需在模板标签使用safe过滤器即可,告诉 Django,这段文本是安全的,你什么也不用做。在模板中找到展示博客文章主体的 {{ post.body }} 部分,为其加上 safe 过滤器,{{ post.body|safe }},大功告成,这下看到预期效果了。
safe 是 Django 模板系统中的过滤器(Filter),可以简单地把它看成是一种函数,其作用是作用于模板变量,将模板变量的值变为经过滤器处理过后的值。例如这里 {{ post.body|safe }},本来 {{ post.body }} 经模板系统渲染后应该显示 body 本身的值,但是在后面加上 safe 过滤器后,渲染的值不再是body 本身的值,而是由 safe 函数处理后返回的值。过滤器的用法是在模板变量后加一个 | 管道符号,再加上过滤器的名称。可以连续使用多个过滤器,例如 {{ var|filter1|filter2 }}。
![](http://opsbzmsv1.bkt.clouddn.com/Markdown%20%E6%B5%8B%E8%AF%95.png)
代码高亮
程序员写博客免不了要插入一些代码,Markdown 的语法使我们容易地书写代码块,但是目前来说,显示的代码块里的代码没有任何颜色,很不美观,也难以阅读,要是能够像我们的编辑器里一样让代码高亮就好了。虽然我们在渲染时使用了 codehilite 拓展,但这只是实现代码高亮的第一步,还需要简单的几步才能达到我们的最终目的。安装 Pygments
首先我们需要安装 Pygments,激活虚拟环境,运行:pip install Pygments安装即可。
搞定了,虽然我们除了安装了一下 Pygments 什么也没做,但 Markdown 使用 Pygments 在后台为我们做了很多事。如果你打开博客详情页,找到一段代码段,在浏览器查看这段代码段的 HTML 源代码,可以发现 Pygments 的工作原理是把代码切分成一个个单词,然后为这些单词添加 css 样式,不同的词应用不同的样式,这样就实现了代码颜色的区分,即高亮了语法。为此,还差最后一步,引入一个样式文件来给这些被添加了样式的单词定义颜色。
引入样式文件
在项目的 blog\static\blog\css\highlights\ 目录下应该能看到很多 .css 样式文件,这些文件是用来提供代码高亮样式的。选择一个你喜欢的样式文件,在 base.html 引入即可(别忘了使用 static 模板标签)。比如我比较喜欢 github.css 的样式,那么引入这个文件:templates/base.html ... <link rel="stylesheet" href="{% static 'blog/css/pace.css' %}"> <link rel="stylesheet" href="{% static 'blog/css/custom.css' %}"> ... + <link rel="stylesheet" href="{% static 'blog/css/highlights/github.css' %}">
这里 + 号表示添加这行代码。好了,看看效果,大功告成,终于可以愉快地贴代码了。
![](http://opsbzmsv1.bkt.clouddn.com/%E4%BB%A3%E7%A0%81%E9%AB%98%E4%BA%AE.png)
注意:如果你按照教程中的方法做完后发现代码依然没有高亮,请依次检查以下步骤:
确保在渲染文本时添加了
markdown.extensions.codehilite拓展,详情见上文。
确保安装了 Pygments。
确保代码块的 Markdown 语法正确,特别是指明该代码块的语言类型,具体请参见上文中 Markdown 的语法示例。
在浏览器端代码块的源代码,看代码是否被 pre 标签包裹,并且代码的每一个单词都被 span 标签包裹,且有一个 class 属性值。如果没有,极有可能是前三步中某个地方出了问题。
确保用于代码高亮的样式文件被正确地引入,具体请参见上文中引入样式文件的讲解。
有些样式文件可能对代码高亮没有作用,首先尝试用 github.css 样式文件做测试。
总结
本章节的代码位于:Step9: markdown and code highlight supported。如果遇到问题,请通过下面的方式寻求帮助。
在 支持 Markdown 语法和代码高亮 - 追梦人物的博客 的评论区留言。
将问题的详细描述通过邮件发送到 djangostudyteam@163.com,一般会在 24 小时内回复。
更多Django 教程,请访问 追梦人物的博客。
相关文章推荐
- 9 - 支持 Markdown 语法和代码高亮
- 支持 Markdown 语法和代码高亮
- 使用类eclipse编辑器开发小程序,支持代码高亮与语法自动提示
- django 简易博客开发 5 markdown支持、代码高亮、gravatar头像服务
- Django+Markdown+Pygments 支持Markdown 实现代码高亮
- sublime text中<script type="text/ecmascript-6">如何代码高亮并支持语法?
- Sublime Text3下两款Markdown插件 支持实时预览与代码高亮
- django 简易博客开发 5 markdown支持、代码高亮、gravatar头像服务
- django 简易博客开发 5 markdown支持、代码高亮、gravatar头像服务
- 代码发芽网:无需插件支持Blog代码高亮,支持近百种编程语言
- 支持多种语言的代码高亮过滤器
- Visual Assist X添加默认包含路径+支持VS2010高亮显示CUDA代码(Windows 7)
- 生成语法高亮代码
- [javascript]简单 方便 易折腾的日历控件,纯javascript支持链式语法,核心代码只有5行
- Word插入代码实现语法彩色高亮显示的办法
- dokuwiki将编辑器修改为可视化,并支持代码高亮和QQ截图拷贝
- 在word中实现代码的语法高亮
- 使用notepad++ 让word里面的代码高亮 支持各种编程语言 3张图片说明
- 很赞的在线的代码编辑器,支持多种语言彩色语法编辑,罕见精品