本站功能与使用指南:siliu.online 一览

这是一份「网站说明书」。如果你第一次来,或者想搞清楚这个站点到底能做什么、怎么用,看这一篇就够了。全文配截图,按「这是个什么站 / 怎么读 / 怎么写 / 技术底座 / 操作速查」来讲。

数据快照(2026-10-31):231 篇文章(199 篇已发布)、28 个分类、98 个标签、3 本合集(共 69 条篇目)、60 条评论。

首页:英雄区 + 最新文章卡片

首页:深色英雄区下面是文章流,顶栏带搜索与「文集 / 管理 / 撰文 / 联系」入口。


一、这是个什么样的站点

它是作者的个人站点,同时具备博客与文集(书)两套能力:

  • 内容主题:Django 技术、结构设计计算、以及生活记录(女儿的成长故事「小薇薇的成长」)。
  • 双格式文章:每篇文章底层可以是 HTML 或 Markdown,但都走同一套渲染层,读者看到的效果一致。
  • 部署形态:跑在家里的一台电脑上,通过纯 IPv6 + 阿里云 DDNS 直连外网;图片全部放在七牛云 CDN;数据库是一个单文件 SQLite。
  • 组织方式:零散文章可以被编进「书」,变成有顺序、分卷、带书摘的可读书。

二、读文章:双格式、代码高亮、可评论

打开任意一篇文章(/post/<id>/),你会看到:

  • 代码高亮:代码块由 highlight.js 上色,深色背景区分正文,关键字、字符串、注释各有颜色。
  • 图片自动分页:长文中的多张图会自动均匀分布到页面各处,不会在某一屏挤成一堆。
  • Markdown 评论:登录后可在文末写评论,支持 Markdown 与实时预览;评论内容会经过净化(防 XSS),但保留你写的格式。

文章页:代码块已高亮

一篇讲 PDF 导出的文章,其中的 Python 代码块被高亮成红/橙/紫等颜色。


三、文集(书):把散篇变成一本可读的书

这是本站最有特色的能力。三个概念要分清:

  • 书(Collection):一本合集,有标题、副标题、封面、简介。
  • 卷(part):书里的分组,比如「卷一 · 把站搬回家」。卷不是单独的表,而是由相邻篇目的 part 字段自然聚成。
  • 篇(Chapter):书里的一篇文章,只引用不复制——它外键指向真正的文章,文章改了,书里跟着变;文章被撤回,篇目自动消失。

阅读路径有三层:书库(/books/) → 某一本书的目录(按卷分组) → 阅读页(带进度条、书内上下篇、本书目录、篇首书摘)。

书库:三本书并排展示封面

书库页:目前有三本——《把博客搬回家》《结构设计笔记》《小薇薇的成长》,各有纯 CSS 生成的封面。

书目录:按卷分组的篇目列表

一本书的目录页:按「卷」分组,每条显示序号、篇名、书摘与日期,点击进入阅读页。


四、阅读页的悬浮目录:平时安静,靠近才展开

这是阅读页上一个「懂分寸」的导航:

  • 默认状态:屏幕右缘只露出几条短短的小横线,不打扰阅读。
  • 靠近时:鼠标移到右缘附近,离指针最近的条目先展开,再像水波一样向两侧荡开,最终整块目录铺满右半边;卷名也作为分组提示淡入。
  • 移开时:不会立刻消失,而是留一段宽限期——手抖、擦边、在面板空隙间移动都不会让它闪退。

阅读页默认态:右缘只有几条小横线

默认态:注意右缘那一列等距的小横线,就是折叠起来的目录。

阅读页展开态:右缘铺开整块目录

展开态:鼠标靠近后,目录由近及远波浪式铺开,按「卷」分组列出全部篇目,当前篇用墨色加粗标出。


五、整本导出 PDF(仅作者)

想把整本书存成离线 PDF?在书的目录页点「导出 PDF」即可(仅作者/超管可见该按钮):

  • 异步生成 + 进度条:启动后弹出遮罩,实时显示「正在生成封面 / 第 N 篇 / 拼装」等阶段进度;生成完再下载,不会卡住页面。
  • 观感接近网页:带纯 CSS 封面同款渐变、文章里的图表、以及 Pygments 高亮的代码块;原文章的有序列表(start=N)也会被正确保留。
  • 下载防接管:最终用 blob 方式触发下载,避免被某些下载工具误拦截。

六、写作后台:Markdown 编辑栏

写文章时,后台装配了一个通用编辑栏组件,长这样:

Markdown 编辑栏组件演示

编辑栏:工具条包含加粗 / 斜体 / 标题 / 列表 / 引用 / 链接 / 图片 / 代码块 / 表格 / 分隔线,外加撤销(↶)重做(↷)、「格式速查」折叠面板与状态栏;下方是一个普通 textarea。

它的特点是:

  • 零依赖、即插即用:给任意 <textarea> 接上就能长出工具条,不绑定任何框架。
  • 撤销/重做自维护快照栈:因为浏览器的原生 Ctrl+Z 无法由按钮触发,这里自己实现了一套。
  • 前后台同款:前台评论的 Markdown 编辑、后台文章的编辑,用的是同一套核心。
  • 富文本 ⇄ Markdown 切换:后台文章可以在 CKEditor 富文本与 Markdown 之间切换,切换时编辑栏会重建工具条与预览。

七、技术底座(一句话版)

  • 纯 IPv6 + 阿里云 DDNS:家宽没有固定 IPv4,前缀还会被运营商轮换,所以用 IPv6 直连,DDNS 每 30 分钟兜底刷新 AAAA 记录;手机用 5G 即可访问。
  • 纯云存储:nginx 不再服务本地媒体,图片/文件全部上七牛 CDN,容器里零本地媒体文件。
  • 单点 SQLite + 自动备份:每周一 06:30 在线热备数据库与媒体并做完整性校验,保留 12 份。
  • Docker 容器化:web / nginx / acme 三个容器,gunicorn 单 worker(避免 SQLite 并发锁)。

八、使用操作速查

读者

  • 浏览:首页看最新文章;或 文集 → 选一本书 → 按卷读 → 阅读页(用右缘悬浮目录快速跳转)。
  • 搜索:顶栏搜索框。
  • 评论:登录后在文末写 Markdown 评论,可实时预览。
  • 订阅:站点 RSS 在 /all/rss/。

作者

  • 发文:本地写好 Markdown,用命令发布(元信息走参数,正文从标准输入喂入):

cat 本地.md | docker exec -i deploy-web-1 python manage.py publish_post - \ --title "标题" --category "Django技术" --tags "a,b,c" \ --author liulinhai --status p

  • 入集:后台用 Chapter 内联表,指定所属书、卷(part)、排序号与书摘。
  • 导出 PDF:在书的目录页点「导出 PDF」(作者可见)。
  • 编辑:后台任意文章可在 Markdown / 富文本间切换,编辑栏工具条随手可用。

九、写在最后

这个站点一路从「云服务器上的能跑博客」长成「结构清楚、好写、好读、好运维」的样子:内容上双格式统一、评论净化、代码高亮一致;组织上用文集把散篇变成有序的书;体验上有悬浮目录与整本 PDF 导出;底座上是纯 IPv6 直连、纯云存储与单点 SQLite 自动备份。

关于这段演进,之前已经写过两篇复盘,都收在《把博客搬回家》合集里:

  • 《网站开发里程碑小结:siliu.online 的架构与特点》——站点的整体架构与特点。
  • 《小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾》——PDF 导出与悬浮目录的迭代细节。

如果你正打算把自己的站点「搬回家」,或者想给博客加一套文集/PDF 能力,这两篇和本文应该能省你不少试错时间。

Last Modified·2026年10月31日 19:02

暂无评论

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