{"repo": "chenyuheee/autoblog-oss", "files": {"README.md": {"4e11016df5be502a9ebf80268975608e672a56b3": {"t": 1785746371.30788, "n": 8152, "h": "cc6f85877a0801ad", "c": "\n\n# AutoBlog\n\n一个使用 Python 编写的轻量级静态博客生成器：将 `source/` 中的 Markdown 构建为 `public/` 下的可部署网站，可直接托管在 GitHub Pages。\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n[](README.md)\n[](README_en.md)\n\n
\n\n## 这是什么？（给想搭博客的你）\n\nAutoBlog 用来把你写的 Markdown 文章生成一个完整的静态博客站点，并且可以一条命令部署到 GitHub Pages。\n\n你会得到：\n\n- 文章页 + 首页列表\n- 标签页、归档页、站内搜索\n- RSS + sitemap（配置 `site_url` 后自动生成）\n\n你只需要：用 Markdown 写文章，执行构建/部署命令。\n\n## 5 分钟上手：从 0 到上线\n\n### 0）准备\n\n- 安装 Python 3.10+\n- 本地有 Git\n- 有一个 GitHub 仓库（用于承载博客）\n\n### 1）克隆项目\n\n```bash\ngit clone https://github.com/ChenyuHeee/AutoBlog\n - label: 首页\n url: /\n - label: 标签\n url: /tags/\n - label: GitHub\n url: https://github.com/ChenyuHeee/AutoBlog\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n\n## Desktop App (PySide6)\n\n提供一个本地桌面应用（非 Web 后台），用于：编辑 config、编辑 Markdown 并实时预览、编辑主题文件、点击构建并打开本地预览。\n\n1) 安装依赖\n\n```bash\npip install -r requirements.txt -r requirements_desktop.txt\n```\n\n2) 启动\n\n```bash\npython run_desktop.py\n```\n\n说明：\n- “构建”会复用 build.py 的逻辑生成 public/\n- “启动预览服务”会在本机起一个静态服务器，然后用系统浏览器打开\n```\n\n### 3）创建你的站点配置\n\n把示例配置复制为正式配置：\n\n```bash\ncp source/config.yaml.example.yaml source/config.yaml\n - label: 邮箱：you@example.com\n url: mailto:you@example.com\n icon: mail\n note: 学习交流欢迎来信\n - label: GitHub @YourName\n url: https://github.com/YourName\n icon: github\n\ngithub_repo: your-user/your-repo\ngithub_branch: gh-pages\ngithub_remote: origin\n\n# 关键：base_url 决定 GitHub Pages 路径\n# 1) 如果是“项目页”（https://your-user.github.io/your-repo/）：\nbase_url: /your-repo/\n# 2) 如果是“个人主页”（https://your-user.github.io/）：\n# base_url: /\n\n# 推荐：填上绝对站点地址以生成 RSS/sitemap 的绝对链接\n# site_url: https://your-user.github.io/your-repo/\n```\n\n### 4）写第一篇文章\n\n在 `source/posts/` 下新建一个 Markdown，例如：\n\n```markdown\n---\ntitle: \"Hello AutoBlog\"\ndate: 2025-12-29\nslug: hello\ndescription: \"我的第一篇博客。\"\n---\n\n这里写正文。\n```\n\n### 5）本地预览\n\n```bash\npython3 build.py\n provider: deepseek\n api_key: \"\" # 推荐使用环境变量 DEEPSEEK_API_KEY\n model: deepseek-chat\n endpoint: https://api.deepseek.com/v1/chat/completions\n temperature: 0.2\n max_input_chars: 6000\n max_tokens: 200\n max_output_chars: 120\n\n```bash\npython3 build.py --deploy\n```\n\n然后到 GitHub 仓库设置里启用 Pages：\n\n- Source 选择 `github_branch`（默认示例是 `gh-pages`）\n- 目录选择仓库根目录（root）\n\n几分钟后即可通过 Pages 地址访问。\n\n## 常见踩坑（最重要的 2 个）\n\n1. 页面路径不对/资源 404：优先检查 `base_url` 是否正确（项目页通常是 `//`）。\n2. RSS / sitemap 里链接不对：补上 `site_url`（带 `https://` 且以 `/` 结尾）。\n\n## 更多功能（按需看）\n\n- 文件夹元数据：`source/posts/**/_meta.yaml` 可以批量追加 tags / 默认字段\n- 合集（collection）：把一个目录折叠成首页一张合集卡片\n- AI 摘要：缺少 `description` 时可用 DeepSeek 自动生成并写回\n\n\n高级配置（config.yaml 参考）
\n\n权威参考：`source/config.yaml.example.yaml`（建议从它复制一份作为 `source/config.yaml` 再改）。\n\n### URL / GitHub Pages\n\n- `github_repo`：`owner/repo`，用于推导默认 Pages 地址与推送目标\n- `github_branch`：承载静态文件的分支（常用 `gh-pages`）\n- `github_remote`：本地 git remote 名称（默认 `origin`）\n- `github_remote_url`：显式指定推送地址（不想依赖本地 remote 或 `github_repo` 时用）\n- `base_url`：资源与路由前缀（项目页通常 `//`；个人主页通常 `/`）\n- `site_url`：站点绝对地址（用于 RSS/sitemap 的绝对链接，必须以 `https://` 开头并以 `/` 结尾）\n\n### 导航栏（可选，自定义）\n\n不配置时会自动生成“首页/归档/标签/页面”。如果你想完全自定义：\n\n```yaml\nnav_links:\n - label: 首页\n url: /\n - label: 标签\n url: /tags/\n - label: GitHub\n url: https://github.com/ChenyuHeee/AutoBlog\n```\n\n### RSS / Sitemap\n\n- `rss_enabled: false`：关闭 RSS（同时会影响页面中 RSS 相关输出）\n\n### 侧栏联系方式\n\n```yaml\ncontacts:\n - label: 邮箱：you@example.com\n url: mailto:you@example.com\n icon: mail\n note: 学习交流欢迎来信\n - label: GitHub @YourName\n url: https://github.com/YourName\n icon: github\n```\n\n### 背景音乐播放器\n\n```yaml\nbackground_music:\n enabled: true\n src: media/your.mp3\n title: \"Song Title\"\n artist: \"Artist\"\n cover: media/cover.jpg\n autoplay: false\n start_muted: true\n```\n\n`src/cover` 对应的是 `source/assets/` 下的相对路径（例如文件放在 `source/assets/media/your.mp3`，这里写 `media/your.mp3`）。\n\n### AI 摘要（DeepSeek）\n\n当文章没写 `description` 时可自动生成摘要并写回 Markdown。\n\n```yaml\nai_summary:\n provider: deepseek\n api_key: \"\" # 推荐使用环境变量 DEEPSEEK_API_KEY\n model: deepseek-chat\n endpoint: https://api.deepseek.com/v1/chat/completions\n temperature: 0.2\n max_input_chars: 6000\n max_tokens: 200\n max_output_chars: 120\n```\n\n \n\n## 可视化管理后台（本地 Web UI）\n\n如果你想通过界面管理 `config.yaml`、编辑文章并实时预览、以及修改主题模板/资源，可以启动本项目自带的本地管理后台。\n\n安装依赖：\n\n```bash\npip install -r requirements.txt -r requirements_admin.txt\n```\n\n启动：\n\n```bash\npython3 -m uvicorn admin.app:app --reload --port 5177\n```\n\n打开：\n\n- 管理后台：`http://127.0.0.1:5177/`\n- 构建后的站点预览：`http://127.0.0.1:5177/preview/`\n\n提示：后台会直接修改仓库里的源文件（例如 `source/config.yaml`、`source/posts/**.md`、`templates/*.html`），建议配合 Git 使用。\n\n\n高级写作（Front Matter / _meta.yaml / 合集 / 置顶）
\n\n### 文章 Front Matter\n\n文章（`source/posts/**/*.md`）支持 YAML Front Matter，例如：\n\n```yaml\n---\ntitle: \"我的第一篇文章\"\ndate: 2025-12-29\nslug: my-first-post\ndescription: \"一句话摘要（用于首页卡片/SEO）。\"\nexcerpt: \"可选：更短的摘要，或给 RSS/列表用。\"\ntags: [AIOps, 论文]\ndraft: false\n\n# 置顶（两种写法都支持）：\npinned: true\n# 或 pinned: 10 （数字也会被当成置顶，并作为优先级参考）\npinned_priority: 0\n---\n```\n\n要点：\n\n- `tags` 支持数组，或字符串（支持逗号/分号/斜杠分隔）。\n- `draft: true` 默认不会输出（用 `python3 build.py --drafts` 才会包含）。\n- `pinned: true` 置顶；`pinned_priority` 越小越靠前；不填默认当作 `0`。\n\n### 目录级 `_meta.yaml`（批量默认值 + 批量标签）\n\n在 `source/posts/` 的任意子目录里放 `_meta.yaml`，它会对该目录及所有子目录文章生效，并且会沿目录层级叠加：\n\n```text\nsource/posts/\n _meta.yaml\n aiops/\n _meta.yaml\n intro.md\n```\n\n支持两类能力：\n\n1) `tags`：会和文章自身 `tags` 合并，去重（大小写不敏感），并且会把合并结果写回到文章 Front Matter，保证下次构建一致。\n\n2) 其它键：作为“默认值”填充到文章 Front Matter（仅当文章缺少该字段时才会填充），同样可能写回文件。\n\n示例：\n\n```yaml\ntags: [AIOps]\ndraft: false\n```\n\n### 合集（collection）\n\n在 `_meta.yaml` 中配置 `collection`，可以把一个目录折叠成首页的一张合集卡片，并生成合集列表页面。\n\n最简单：\n\n```yaml\ncollection: true\n```\n\n完整写法（可覆盖标题/描述/排序/标签）：\n\n```yaml\ncollection:\n enabled: true\n title: \"AIOps 学习笔记\"\n description: \"论文精读、项目复现与实践记录。\"\n order: 10\n tags: [AIOps, 论文]\n```\n\n关闭合集（对某个子目录禁用）：\n\n```yaml\ncollection: false\n# 或\ncollection:\n enabled: false\n```\n\n说明：\n\n- `order` 越小越靠前（用于首页排序）。\n- `tags` 不填时，会从该合集内文章的 tags 统计出出现频率最高的前 4 个作为合集卡片标签。\n\n### 一个容易忽略的点：构建可能会“写回”Markdown\n\n构建时会自动规范化 tags、补默认值；如果开启了 AI 摘要，还会把生成的 `description` 写回到 Markdown。\n\n \n\n\n仓库状态面板（图表/炫技）
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n\n\n工具脚本（偏开发/维护）
\n\n- `scripts/package_project.py`：将项目拷贝到 `dist/`（可加 `--zip` 打包）。\n- `scripts/publish_open_source.py`：发布“脱敏 + 单提交历史”的快照分支到远程。\n\n \n\n## 许可证\n\nMIT\n"}}}}