散篇变成书的第一步,是承认它们本来就有顺序。
把文章编成书:给博客加一个「文集」板块
写了两年多的博客,攒下两百多篇文章。它们按时间排,按分类和标签横向归档,读起来却始终是一个个散篇——「上一篇 / 下一篇」只是全站时间序,没有任何顺序可言。
可有些文章天生是有顺序的。比如最近这一轮把站点搬回家的十几篇记录,从 IPv6 直连、DDNS、容器化,到 Markdown 编辑器、纯云存储,再到 Django 4.2 升级,它们是一条完整的施工线,应该像一本书那样被从头读到尾。
于是给站点加了一个「文集」板块:把已经发表的文章编成一本有卷、有序号、有书摘的书。这篇文章记录它的设计与实现,以及过程中踩到的几个坑。
一、定三条约束
动工之前先定下三条约束,后面所有设计都是它们的推论。
1. 只引用,不复制正文
书里的篇目只存一个指向文章的外键,绝不另存一份正文。理由很实在:一旦复制,两处内容必然分叉——文章改了错别字,书里还是旧的。
这条约束带出一个意外的好处:篇目是否可见,可以直接跟着文章的状态走。文章撤回(status != 'p'),书里自动不出现;改回已发布,又自动回来。篇目记录一直留着,不用人工维护。
2. 序号不落库
「第 N 篇」不存进数据库。后台只填排序号(10、20、30……),页面上的连续序号由视图按最终顺序现场 enumerate 出来。
def chapter_entries(self):
"""[(第几篇, 篇目), ...],序号现算,不落库。"""
return list(enumerate(
self.chapters.filter(post__status='p').order_by('order', 'id'),
start=1))
这样中间插一篇,只需要给它一个 25 的排序号,后面所有篇目的「第几篇」依然连续,不用批量改写任何数据。如果序号是字段,每插一篇都要把后面几十条全部 +1。
3. 卷是排序的自然产物
不建「卷」表。同一卷的篇目只要是排序号相邻、且卷名相同,目录页就把它们聚成一屏,卷标题当场生成。
def sections(self):
"""把相邻的同卷篇目聚成一段:[(卷名, [(序号, 篇目), ...]), ...]"""
少一张表,少一层维护,也少一个「忘了给卷排序」的出错点。
二、两张表
class Collection(models.Model): # 一本书
title = models.CharField('书名', max_length=80, unique=True)
slug = models.SlugField('网址标识', max_length=80, unique=True, blank=True)
subtitle = models.CharField('副标题', max_length=120, blank=True)
author = models.ForeignKey(User, verbose_name='编著者', null=True, blank=True,
on_delete=models.SET_NULL)
cover = models.ImageField('封面', upload_to='covers/', blank=True, null=True)
intro = models.TextField('简介', blank=True)
epigraph = models.TextField('书摘', blank=True) # 扉页引文,一行一条
status = models.CharField('状态', max_length=1, choices=STATUS_CHOICES, default='d')
sort_order= models.IntegerField('排序', default=0)
class Chapter(models.Model): # 书里的一篇
collection = models.ForeignKey(Collection, related_name='chapters',
on_delete=models.CASCADE)
post = models.ForeignKey(Post, related_name='book_chapters',
on_delete=models.CASCADE)
order = models.IntegerField('排序', default=0)
part = models.CharField('卷/部', max_length=40, blank=True)
title = models.CharField('篇名', max_length=90, blank=True) # 留空用原标题
epigraph = models.TextField('书摘', blank=True) # 篇首题记
class Meta:
ordering = ['order', 'id']
unique_together = [('collection', 'post')]
unique_together 保证同一篇文章在一本书里只出现一次,但不同书可以重复收录同一篇——一篇文章可能既属于「搬迁记」,也属于「Django 实践」。
书摘留了两处:扉页书摘(整本书的引文)和篇首题记(每篇的摘录),对应书里真实存在的两个位置,格式都是「一行一条」。
slug 有个小细节:中文标题 slugify 出来是空的,URL 会变成一串 %E6%8A%8A%E5%8D%9A...。所以 save() 里加了兜底——自动生成不了就退成 book-<8位随机>,保证 URL 永远干净。
三、三张页面
| 路径 | 内容 |
|---|---|
/books/ |
书库:封面墙 |
/books/<slug>/ |
目录:封面 + 简介 + 扉页书摘 + 按卷分组的篇目表 |
/books/<slug>/<int:seq>/ |
阅读:第 seq 篇,带进度条和书内上下篇 |
阅读页的 URL 用「第几篇」而不是文章主键。/books/bring-blog-home/3/ 比 /books/bring-blog-home/57/ 可读得多,读者也能从地址栏看出进度。副作用是插一篇会让后面的 URL 变,但这类内容型 URL 本来就该跟着内容走。
阅读页正文直接复用文章自己那套渲染层(post.rendered_body),Markdown 和富文本两种格式都不用另写一遍;正文之外再叠上篇首题记、进度条、书内上一篇/下一篇,以及一个折叠的「本书目录」。
没有封面也能看
上传封面不是必须的。没传封面时,用书名排版生成一张纯 CSS 封面:四套配色按主键轮换,加一条书脊,零图片依赖。这样新建一本书就能立刻看到效果,等有合适的图再换。
反查:从文章回到书
文章详情页标题下方会显示「收录于《把博客搬回家》第 1 篇」,点进去就是书内那一篇。用一个模板标签 {% book_refs post %} 实现,一篇文章被多本书收录时都列出来。
四、后台:编排与批量收录
书编辑页里,篇目是内联表格,直接改排序号、卷名、篇名、题记即可;文章字段用自动补全(复用文章后台的搜索),两百多篇文章里挑一篇不用翻页。
但从文章那一侧进书更顺手:写完几篇文章,勾一勾就应该能成书。所以给文章列表加了一个动作:
勾选若干文章 → 「添加到合集(书)…」→ 中间页:选书 / 新建一本 / 定卷 / 定顺序 → 完成
中间页刻意做得轻,只问四件事:放进哪本书(或直接新建)、归到哪一卷、按什么顺序(发布时间从早到晚,或保持勾选顺序)、起始排序号(留空则自动接在书末)。篇名和书摘留给书的编辑页逐篇补——批量操作不该逼人当场写完所有题记。
实现上是 admin action 加一个中间页:
def add_to_collection(self, request, queryset):
ids = ','.join(str(pk) for pk in queryset.values_list('pk', flat=True))
return redirect('%s?ids=%s' % (reverse('admin:blog_post_add_to_collection'), ids))
action 本身是 POST,渲染不了表单页,所以只把主键拼进查询串,重定向到挂在 admin 命名空间下的表单视图(admin_view 包一层,复用后台登录态与 CSRF)。视图里用 self.get_queryset(request) 取文章,这样非超管账号只能操作自己的文章。
顺带在文章列表加了一列「已收录于」,直接显示《书名》第几篇并链到书内阅读页,不用再猜某篇文章有没有入书。
links.append((reverse('anthology:read',
kwargs={'slug': ch.collection.slug, 'seq': seq}),
ch.collection.title, seq))
一个权限坑
功能上线后,管理员(超管)能看到「合集(书)」,其他编辑账号却完全没有入口。查下来不是注册问题:Collection 早就注册进 admin,超管首页 HTML 里也有那一块。真正原因是权限——站内十个非超管账号都在「编辑」组,而这个组只有 blog 应用的权限,一条 anthology 权限都没有。
Django 后台首页的 get_app_list() 只列出当前用户有 view 权限的模型,于是整个「合集(书)」区块干脆不渲染,从界面上看就像功能没上线。
Group.objects.get(name='编辑').permissions.add(
*Permission.objects.filter(content_type__app_label='anthology'))
补上八条权限后,编辑账号也能正常使用了。新增 app 之后,记得同步给非超管组授权,否则「明明上线了、别人却看不到」会被误判成注册失败。
五、踩坑记录
1. 迁移文件生成不出来。 新代码在宿主机上,而 Django 只在容器镜像里。解法是把宿主机目录挂进旧镜像跑命令:
docker run --rm -i -v D:/web/app/blogproject:/app -w /app \
deploy-web python manage.py makemigrations anthology
注意那个 -i:用 heredoc 经 stdin 喂脚本时,不带 -i 脚本会静默不执行,命令看着成功其实什么都没发生。
2. docker-compose build 报 project name must not be empty。 一直用的是工作区里那份 docker-compose.yml(中文路径),而容器实际是由 D:\web\deploy 那份配置启动的。中文目录名会被清洗成空字符串。认准 D:\web\deploy。
3. 书摘的引号。 书摘渲染成「」包裹的引文,最初用 ::before/::after 插引号,结果开引号和正文之间被撑开一大段空白——伪元素继承到了父级的居中排版。改成引号与文字同一个行内元素,间距才正常。
4. 移动端截图右侧被切。 一度以为是布局溢出,后来发现是 Windows 无头浏览器窗口有最小宽度限制,首页同样如此,不是页面问题。判断布局要看 DOM 实测宽度,别只信截图。
六、还能做什么
目前书的三个页面都能用,样例书《把博客搬回家》收了十二篇、分三卷。后续可以做:正文里浮动的「第 N 篇 / 共 M 篇」导航、整本书的 RSS、把某一卷导出成 PDF,或者给书加一个独立的阅读进度记忆(读到第几篇下次接着读)。
不过最要紧的先做完了:文章终于有了顺序。
定稿于 2026.10.30
本书目录
- 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
- 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
- 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
- 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
- 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
- 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
- 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
- 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
- 09 编辑栏合并成一套,顺手补上撤销重做
- 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
- 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
- 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
- 13 把文章编成书:给博客加一个「文集」板块
- 14 网站开发里程碑小结:siliu.online 的架构与特点
- 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
- 16 本站功能与使用指南:siliu.online 一览
- 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器