djhx-blogger

把 Markdown 文件夹变成一个可阅读、可搜索的静态博客。blg 支持增量构建、图片优化、文章归档、草稿标记，以及经过校验的 SSH 部署。

Python ≥ 3.10 · Windows / macOS / Linux · 无前端构建工具 · 无 CDN 依赖

开始使用

uv tool install djhx-blogger
blg --version
blg --help

已有博客：

blg -o "C:\Project\blog" -t "C:\Project\blog-output"
python -m http.server 8000 --directory "C:\Project\blog-output\public"

浏览器打开 http://localhost:8000。-t 指定输出的父目录，生成结果在其下的 public/。源目录和输出目录必须分开。

创建一个示例：

blg -n ./demo
blg -o ./demo/simple-blog -t ./output

文章格式

blog/
├── about/index.md
└── software/
    └── 第一篇文章/
        ├── index.md
        ├── images/example.png
        └── attachment.pdf

index.md 所在目录是文章；其他内容目录是分类。普通 .md 文件也会生成同名 .html 页面。附件原样复制，images/ 只存放资源，不生成分类页。

---
title: "第一篇文章"
date: 2026-10-01T09:30:00+08:00
summary: "这篇文章讨论什么。"
draft: true
---

## 开始

正文，支持代码块、表格和 [TOC]。

draft: true 表示未完成，文章页、分类页和归档都会显示标记。草稿仍然发布并参与搜索，不能用它隐藏秘密。写完后改为 draft: false，或删除这个字段。旧文章没有标记时按已完成处理。

blg -o ./blog -p "software/新文章"

新文章默认是草稿，不覆盖已有文章。

配置与部署

blg -c                          # 查看默认配置路径
blg --config ./config.toml      # 使用指定配置
blg --archive                   # 构建并打包，使用配置中的源/输出路径
blg -d                         # 构建 → 打包 → SSH 部署 → 刷新搜索
uv tool upgrade djhx-blogger

配置示例见 config.example.toml。原来的 [local]、[deploy] 配置和 -o/-t/-s/-T/-d/-n/-p/-c 保留；命令行值优先。

远程部署需要 Linux、Python 3.9+、可信的 SSH host key，以及目标目录的写权限。默认 SSH 用户仍为 koril，可配置；SSH 默认使用密钥或 agent，密码认证使用 --password。SSH 密码和 sudo 密码分开输入。部署按完整 release 切换，保留上一版 blog.bak；迁移步骤见部署文档。

这次翻修解决了什么

构建在独立暂存目录进行，任何转换或图片任务失败都会保留旧站点；重复调用不再受全局进程池影响。
文件按内容校验缓存，未变化的 HTML 和图片自动复用，删除的源文件不会残留在新站点。
正确读取 YAML、BOM、CRLF、带时区日期、多行摘要与缺省元数据，标题统一使用 title。
保留图片透明度和动画，处理 JPEG 方向；附件不再误当图片，损坏图片会报错。
所有模板元信息默认转义，链接使用 URL 编码；拒绝路径重叠、符号链接、输出冲突和目录穿越。
部署校验 SSH 主机、上传摘要和归档成员，先准备新站点再切换，防止命令注入和半成品上线。
本地样式与代码高亮，浅色/深色主题，响应式目录、搜索表单、代码复制和键盘可访问性。

文档导航

文档	内容
使用手册	命令、目录规则、元数据、图片、草稿和故障排查
配置参考	完整配置项、默认值、迁移与优先级
架构与取舍	三个项目的关系、构建事务、缓存、并发和部署协议
页面设计	排版、主题、响应式与搜索服务的 HTML 约定
开发指南	模块、测试、检查、调试、扩展方法
部署与回滚	SSH、release 布局、旧版迁移、恢复和搜索刷新
发布流程	构建检查、PyPI token、发布与 uv tool 更新
修复与验证记录	原问题、修复、验证范围和性能实测
草稿整理记录	本次补标的文章与判断依据
版本记录	0.3.0 的改动与兼容说明

开发

uv sync --group dev
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv build
uv run twine check dist/djhx_blogger-0.3.0*

Markdown 正文允许作者编写原始 HTML。输入应来自可信作者；它不是针对不可信多用户投稿的 HTML 清洗服务。其他安全边界见架构文档。

MIT License。

Metadata

Release files for djhx-blogger 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for djhx-blogger 0.3.0
File	Size	Uploaded
djhx_blogger-0.3.0.tar.gz	880.3 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for djhx-blogger 0.3.0
File	Interpreter	ABI	Platform	Reset
djhx_blogger-0.3.0-py3-none-any.whl 747.4 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 1.6 MB

Release files / djhx_blogger-0.3.0.tar.gz

Download URL	djhx_blogger-0.3.0.tar.gz
Size	880.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`9716f31bb60292578fcf1c08531917c5efeed3da4956ebbf606bdd44cdac2508`
BLAKE2b-256 checksum How to use checksums	`6d91e0fe5f7866aaa2c0db26f50e43c1f78a5bdbcbeeceb9fbb6f4b27d4e7a9a`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.4`

Release files / djhx_blogger-0.3.0-py3-none-any.whl

Download URL	djhx_blogger-0.3.0-py3-none-any.whl
Size	747.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6ced7615b3b4430d0941dda31b853f91b9747268078bfd799722e5298ca48e1a`
BLAKE2b-256 checksum How to use checksums	`d91c78c595ebb2b4dbb9bbd8a257b73c4ccb57740f6477e4ed1fbdf08b4ca9e6`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.4`