把文章编成书:给博客加一个「文集」板块

liulinhai 2026.10.30 8:00 14 0
Django技术 Django 博客改造 文集

收录于《把博客搬回家》第 13 篇

把文章编成书:给博客加一个「文集」板块

写了两年多的博客,攒下两百多篇文章。它们按时间排,按分类和标签横向归档,读起来却始终是一个个散篇——「上一篇 / 下一篇」只是全站时间序,没有任何顺序可言。

可有些文章天生是有顺序的。比如最近这一轮把站点搬回家的十几篇记录,从 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,或者给书加一个独立的阅读进度记忆(读到第几篇下次接着读)。

不过最要紧的先做完了:文章终于有了顺序。

Last Modified·2026年10月30日 08:00

暂无评论

您尚未登录,请先才能评论。