整合营销服务商
电脑端+手机端+微信端=数据同步管理
免费咨询热线：
电脑端+手机端+微信端=数据同步管理
免费咨询热线：
最近准备搭建一个简单的文档平台，用于组内的文档管理。作为一个程序员，大多数情况下咱们写文档使用的都是markdown语法，比如wiki、hexo、github，然后在浏览器上展示。
目前大部分的编辑器都有自己的markdown插件并支持实时预览，如下图，
图1
此图是vscode编辑器，左侧是markdown文件，右侧是实时预览的界面，咱们这次的目标就是将markdown在浏览器上展示成这个样式。
为了将markdown在浏览器上展示就必须先将markdown转化为html，有了明确的需求就可以去网上搜寻一下工具，我们很容易就能找到一个使用非常频繁的工具——marked。
图2
如图2，它支持在页面中编译markdown代码，但是我们更希望先在后台完成编译的工作再将编译的产物放到页面中使用，这样页面的性能会提示一丢丢，因此我们使用它的node方式。
图3
如图3，node编译markdown的步骤也十分简单，仅需以下几步，
图4
如图4，左侧是markdown编译后的html，右侧是在浏览器中展示的情况，此时完全没有任何样式，所以我们还需要为它配置主题。我们选用最流行的样式——github-markdown-css，把它引入到文件中，再看看效果。
图5
现在页面已经有样式了，和github的readme展示的样式一样，但是你会发现两个问题，
注意：编译产物最外层需要包一层容器，容器的class名字为markdown-body，否则样式不生效。
为了解决上面第一个问题，我们将marked模块换成markdown-it模块，用法如下，
图6
此时markdown的大部分语法都已经支持了，但仍有个别语法不支持，不过不要紧，我们可以将markdown-it的html参数设置为true，这样用户可以直接用html语法写markdown。
代码块没有高亮是不可接受的，这会让同志们的浏览欲望大大降低。对比了一下highlight.js，我选择了prism.js。不为别的，就是因为它满足了我的要求。有人说prismjs比highlight.js对样式控制的更精细，不过I don't care it。
图7
如图7，我一眼就看中了这个主题，有趣。那还等什么，直接把js和css都down下来，引入页面。现在咱们再去看看效果，如下图，
图8
和我的编辑器主题一样。
到这里我们已经完成了我们的需求。
将markdown转化为html其实就两步，一是选择编译工具，需要尽可能多的支持markdown语法，二是选主题，需要看着养眼。
喜欢我的文章就关注我吧，有问题可以发表评论，我们一起学习，共同成长！
者：HelloGitHub-追梦人物
文中涉及的示例代码，已同步更新到HelloGitHub-Team 仓库[1]
为了让博客文章具有良好的排版，显示更加丰富的格式，我们使用 Markdown 语法来书写博文。Markdown 是一种 HTML 文本标记语言，只要遵循它约定的语法格式，Markdown 的解析工具就能够把 Markdown 文档转换为标准的 HTML 文档，从而使文章呈现更加丰富的格式，例如标题、列表、代码块等等 HTML 元素。由于 Markdown 语法简单直观，不用超过 5 分钟就可以轻松掌握常用的标记语法，因此大家青睐使用 Markdown 书写 HTML 文档。下面让我们的博客也支持使用 Markdown 写作。
安装 Python Markdown
将 Markdown 格式的文本解析成标准的 HTML 文档是一个复杂的工程，好在已有好心人帮我们完成了这些工作，直接拿来使用即可。首先安装 Markdown，这是一个 Python 第三方库，在项目根目录下运行命令 pipenv install markdown。
在 detail 视图中解析 Markdown
将 Markdown 格式的文本解析成 HTML 文本非常简单，只需调用这个库的 markdown 方法。我们书写的博客文章内容存在 Post 的 body 属性里，回到我们的详情页视图函数，对 post 的 body 的值做一下解析，把 Markdown 文本转为 HTML 文本再传递给模板：
blog/views.py
import markdown
from django.shortcuts import get_object_or_404, render
from .models import Post
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})
这样我们在模板中显示 {{ post.body }} 的时候，就不再是原始的 Markdown 文本了，而是解析过后的 HTML 文本。注意这里我们给 markdown 解析函数传递了额外的参数 extensions，它是对 Markdown 语法的拓展，这里使用了三个拓展，分别是 extra、codehilite、toc。extra 本身包含很多基础拓展，而 codehilite 是语法高亮拓展，这为后面的实现代码高亮功能提供基础，而 toc 则允许自动生成目录（在以后会介绍）。
来测试一下效果，进入后台，这次我们发布一篇用 Markdown 语法写的测试文章看看，你可以使用以下的 Markdown 测试代码进行测试，也可以自己书写你喜欢的 Markdown 文本。假设你是 Markdown 新手请参考一下这些教程，一定学一下，保证你可以在 5 分钟内掌握常用的语法格式，而以后对你写作受用无穷。可谓充电 5 分钟，通话 2 小时。以下是我学习中的一些参考资料：
?Markdown——入门指南[2]
?Markdown 语法说明[3]
# 一级标题
## 二级标题
### 三级标题
- 列表项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 引入图片的语法为：。
我们在发布的文章详情页没有看到预期的效果，而是类似于一堆乱码一样的 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 }}。
程序员写博客免不了要插入一些代码，Markdown 的语法使我们容易地书写代码块，但是目前来说，显示的代码块里的代码没有任何颜色，很不美观，也难以阅读，要是能够像代码编辑器里一样让代码高亮就好了。
代码高亮我们借助 js 插件来实现，其原理就是 js 解析整个 html 页面，然后找到代码块元素，为代码块中的元素添加样式。我们使用的插件叫做 highlight.js 和 highlightjs-line-numbers.js，前者提供基础的代码高亮，后者为代码块添加行号。
首先在 base.html 的 head 标签里引入代码高亮的样式，有多种样式供你选择，这里我们选择 GitHub 主题的样式。样式文件直接通过 CDN 引入，同时在 style 标签里自定义了一点元素样式，使得代码块的显示效果更加完美。
<head>
...
<link href="https://cdn.bootcss.com/highlight.js/9.15.8/styles/github.min.css" rel="stylesheet">
<style>
.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; ~
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;
}
</style>
</head>
然后是引入 js 文件，因为应该等整个页面加载完，插件再去解析代码块，所以把 js 文件的引入放在 body 底部：
<body> <script src="https://cdn.bootcss.com/highlight.js/9.15.8/highlight.min.js"></script> <script src="https://cdn.bootcss.com/highlightjs-line-numbers.js/2.7.0/highlightjs-line-numbers.min.js"></script> <script> hljs.initHighlightingOnLoad(); hljs.initLineNumbersOnLoad(); </script> </body>
非常简单，通过 CDN 引入 highlight.js 和 highlightjs-line-numbers.js，然后初始化了两个插件。再来看下效果，非常完美！
References
[1] HelloGitHub-Team 仓库: https://github.com/HelloGitHub-Team/HelloDjango-blog-tutorial
[2] Markdown——入门指南: http://www.jianshu.com/p/1e402922ee32/
[3] Markdown 语法说明: http://www.appinn.com/markdown/
欢迎关注 HelloGitHub 公众号，获取更多开源项目的资料和内容
『讲解开源项目系列』启动——让对开源项目感兴趣的人不再畏惧、让开源项目的发起者不再孤单。跟着我们的文章，你会发现编程的乐趣、使用和发现参与开源项目如此简单。欢迎联系我们给我们投稿，让更多人爱上开源、贡献开源～
## Markdown-it-py库详细介绍
在日常的软件开发和内容创作中，Markdown已经成为了一种广泛使用的轻量级标记语言。它简洁、易读易写，并且支持丰富的扩展功能，因此受到了广大开发者和写作者的喜爱。在Python开发领域，有一个非常流行的Markdown解析器库就是markdown-it-py。本文将详细介绍markdown-it-py库的使用方法、特性以及如何集成到你的项目中。
markdown-it-py是一个用于解析和渲染Markdown文本的Python库。它基于流行的JavaScript库markdown-it开发而来，提供了类似的功能和灵活的插件扩展机制。通过markdown-it-py，你可以将Markdown格式的文本解析为HTML或其他格式，或者从HTML转换为Markdown。
首先，你需要通过pip安装markdown-it-py库：
pip install markdown-it-py
安装完成后，你就可以在你的Python项目中引入并使用它了。
让我们来看一个简单的例子，演示如何使用markdown-it-py来解析Markdown文本并将其转换为HTML：
from markdown_it import MarkdownIt
# 创建MarkdownIt实例
md=MarkdownIt()
# 要解析的Markdown文本
markdown_text="""
# 这是标题
这是一个 **粗体** 和 *斜体* 文本示例。
- 列表项 1
- 列表项 2
"""
# 将Markdown转换为HTML
html_content=md.render(markdown_text)
print(html_content)
在上面的例子中，我们首先创建了一个MarkdownIt的实例md，然后通过render方法将Markdown格式的文本markdown_text转换为HTML格式的html_content。运行代码后，html_content将包含以下内容：
<h1>这是标题</h1>
<p>这是一个 <strong>粗体</strong> 和 <em>斜体</em> 文本示例。</p>
<ul>
<li>列表项 1</li>
<li>列表项 2</li>
</ul>
markdown-it-py支持通过插件扩展其功能。例如，你可以添加代码高亮、表格支持、自定义语法等功能。以下是一个添加代码高亮插件的示例：
from markdown_it.plugins import PluginPygments
# 创建MarkdownIt实例
md=MarkdownIt()
# 添加代码高亮插件
md.use(PluginPygments())
# 要解析的Markdown文本
markdown_text="""
```python
print("Hello, World!")
"""
html_content=md.render(markdown_text)
print(html_content)
```
通过PluginPygments插件，我们可以轻松地实现代码块的语法高亮效果。
markdown-it-py是一个功能强大且易于使用的Markdown解析器库，它为Python开发者提供了处理Markdown文本的便捷方法。无论是用于构建静态网页、生成文档，还是集成到自动化脚本中处理文本，markdown-it-py都能够满足你的需求。通过本文的介绍，希望能够帮助你更好地理解和使用这个优秀的工具。
*请认真填写需求信息，我们会在24小时内与您取得联系。
