文集 / 把博客搬回家

第 5 篇·共 17 篇

卷二 · 编辑器与格式

用 Markdown 写博客:一篇示例,也是本站的格式说明

2026年10月27日 ·查看目录

格式不只是排版问题,它是数据模型里必须先说清楚的一件事。

这篇文章是怎么来的

它不是用后台的可视化编辑器排出来的,而是用 Markdown 源码写成、然后一条命令发到站上的。

发布时用的是这个命令:

docker exec deploy-web-1 python manage.py publish_post article.md \
    --title "用 Markdown 写博客:一篇示例,也是本站的格式说明" \
    --tags "Markdown,写作,站点公告"

正文开头那段 --- 包围的内容叫 front-matter,用来声明标题、摘要、标签、分类:

---
title: "文章标题"
excerpt: "文章摘要"
tags: [Markdown, 写作]
category: Django技术
status: p
---

正文从这里开始……

排版能力一览

Markdown 源文本在这里,页面上会显示为正常段落。粗体、斜体、行内代码 都能正确显示。

引用块长这样:左侧一条竖线,文字略微倾斜,用来放引述或提示。

表格

能力 写法 支持情况
标题 # 标题 ✅
粗体 / 斜体 **粗** / *斜* ✅
行内代码 `code` ✅
围栏代码块 ```lang ✅ 带语法高亮
表格 \| 列 \| 列 \| ✅
引用块 > 引用 ✅
列表 - 项 / 1. 项 ✅ 支持嵌套
分隔线 --- ✅
链接 [文字](地址) ✅
图片 ![说明](地址) ✅ 自动限宽

代码高亮

Python 代码:

def render_body(body, content_format):
    """把数据库里的原文转成页面要显示的 HTML。"""
    if content_format == FORMAT_MARKDOWN:
        return mark_safe(_markdown_to_html(body))
    return mark_safe(body)

Shell 命令:

curl -s --noproxy '*' -m 15 -o /dev/null -w "HTTP %{http_code}\n" http://siliu.online/

列表

无序列表:

  • 第一项
  • 第二项
  • 嵌套一项
  • 嵌套二项
  • 第三项

有序列表:

  1. 第一步
  2. 第二步
  3. 第三步

写在最后

从这篇开始,博客可以有两种写法:后台的可视化编辑器适合随手记,Markdown 源码适合写带表格和代码的技术文章。

两种格式可以混用——每篇文章各自记录自己用的是哪一种,页面按各自的方式渲染,互不干扰。

定稿于 2026.10.27

本书目录
  1. 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
  2. 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
  3. 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
  4. 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
  5. 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
  6. 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
  7. 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
  8. 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
  9. 09 编辑栏合并成一套,顺手补上撤销重做
  10. 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
  11. 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
  12. 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
  13. 13 把文章编成书:给博客加一个「文集」板块
  14. 14 网站开发里程碑小结:siliu.online 的架构与特点
  15. 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
  16. 16 本站功能与使用指南:siliu.online 一览
  17. 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器