Content Console 使用指南

#Content Console#指南 共 2,467 字 约 8 分钟

astro-whono 提供一个本地 Content Console，用于在开发环境中管理站点的写作内容。

Content Console 的入口是 /admin/content/。它覆盖随笔、絮语、小记、关于四类内容的浏览、查找、编辑与预览，并支持新建草稿、下载源文件与删除，便于在不直接手写 frontmatter 的情况下维护内容。

开发环境

/admin/content/ 及其编辑页仅在开发环境可操作。生产环境访问时只显示本地开发提示，不加载内容数据与编辑器；/api/admin/content/* 仅服务本地后台，不作为公开 API。

本地启动与入口

本地开发时，可通过以下命令启动项目：

Bash
UTF-8|2 Lines|
npm install
npm run dev

默认情况下，开发服务器会运行在 http://localhost:4321/。启动后可直接访问：

Text
UTF-8|1 Line|
http://localhost:4321/admin/content/

如果本地修改了开发端口，请将 4321 替换为实际端口。

Content Console 直接读取 src/content/** 下的源文件，不依赖数据库或外部服务。新建、保存与删除都会落到仓库内的内容文件，相关改动可通过 Git 跟踪和回退。

内容类型与能力

Content Console 统一管理四类内容，但它们的能力并不相同：

内容目录新建编辑删除列表筛选
随笔src/content/essay/支持支持支持支持
絮语src/content/bits/支持支持支持支持
小记src/content/memo/index.md—支持——
关于src/content/about/index.md—支持——

随笔与絮语是多条内容，可在控制台新建草稿、逐条编辑与删除，列表也提供筛选与分页。小记与关于是固定单页内容，只能编辑现有正文，不支持新建或删除。

浏览、筛选与搜索

打开 /admin/content/ 时，默认按随笔、絮语、小记、关于分组展示内容概览。顶部工具栏提供以下能力：

  • 搜索：按标题、标签或 slug 跨内容查找
  • 范围：在「全部内容」与单类内容之间切换
  • 状态：全部状态 / 已发布 / 仅草稿
  • 排序：最近更新 / 标题 A-Z
  • 年份：按内容年份过滤

状态、排序、年份筛选与分页仅对随笔、絮语生效；小记与关于是固定单页，不暴露这些筛选项。列表中，草稿标记为 [draft]，关闭归档的随笔标记为 [archive off]。

每一项都提供「编辑」按钮，以及「更多」菜单中的修改信息、前台查看、下载与删除操作。

新建与编辑

随笔

在随笔分组点击「新建文章」，填写标题等基础信息后会生成一篇草稿，并跳转到编辑页。

随笔编辑页提供：

  • 基于 CodeMirror 的正文编辑区，内置多种语法高亮主题与行号选项
  • 编辑 / 预览布局切换，预览由服务端渲染
  • frontmatter 信息面板：发布日期、更新日期、标签、草稿与归档等字段
  • 目录与 Markdown 语法两个辅助侧栏
  • 工具栏：常用 Markdown、数学公式、emoji、图片与画廊
  • 正文图片上传：上传后保存到当前内容的附件目录，并插入 Markdown

絮语

在絮语分组点击「新建动态」，选择发布时间后会生成一条草稿并跳转到编辑页。

絮语编辑页是独立工作台，可编辑正文、基础信息与配图（images）行，支持图片上传，并提供实时卡片预览，所见与 /bits/ 列表中的卡片一致。

小记与关于

小记与关于是固定单页内容，编辑页只处理正文：

  • 小记：编辑 src/content/memo/index.md 正文，支持插入正文图片、页面预览与正文目录
  • 关于：编辑 src/content/about/index.md 正文，预览中的友链与 FAQ 会按公开页样式渲染；联系链接位置用 ::contact-links 占位控制

小记与关于的页面主副标题不在这里维护，统一在 Theme Console 调整。

批量操作

勾选列表中的内容后，可通过「批量操作」执行：

  • 发布 / 改草稿：批量切换 draft 状态
  • 下载：把所选内容的源文件打包成 zip 下载
  • 删除：批量删除所选内容，源文件移入回收站（删除前会确认）

批量操作的范围是当前列表中已勾选的内容；可以先用筛选或搜索缩小范围，再批量处理。

下载与删除

  • 下载：在该条的「更多」菜单点「下载源文件」，得到对应的 Markdown 文件
  • 删除：在该条的「更多」菜单中删除，源文件会被移入回收站，而不是直接抹除；删除前会确认

下载与删除作用于源文件本身。删除仅随笔、絮语支持，小记与关于不提供删除。

内容字段与写作约定

Content Console 负责录入和维护内容，具体的 frontmatter 字段、图片路径规则与正文写作约定（Callout、Figure、Gallery、公式等）仍以仓库 README 「内容与写作」为准，这里不再重复。

新建的内容默认是草稿。随笔、絮语的草稿在本地开发可见，生产构建、RSS 与公开列表会自动过滤；小记是单页内容，不应标记为草稿。

写在最后

为什么会做一个本地后台

Content Console 是整个后台里最复杂、投入时间最多的部分。既然都在本地写作、都要启动开发服务器，直接编辑 Markdown 也能完成，可能会有朋友疑惑为什么还要做这样一套后台？

  • astro-whono 面向的用户不一定熟悉前端。直接编辑源文件需要记住 frontmatter 字段、目录结构和写作约定，后台把这些收进表单与按钮，降低上手门槛。
  • 写作时更关心最终的排版效果。编辑页内置服务端预览，正文、卡片与关于页都能在保存前看到接近前台的呈现，不必来回切到浏览器确认。
  • 常用的内容格式（Callout、图片、画廊、公式、emoji 等）可以从工具栏直接插入，省去手写标记和查阅文档。
  • 小记、关于这类固定单页，过去只能改源文件；现在可以在后台原位编辑正文并预览，更方便。

Content Console 的目标不是替代命令行或编辑器，而是让没有代码基础的人也能顺手维护自己的内容。当然最好的方案还是做成真正的 CMS ，但那是另一个量级的工作了，也不在近期计划内。

🔜当前进度与后续计划

Content Console 最初设想的功能目前基本实现，Admin 后台后续也会以维护和细节优化为主，暂时没有继续叠加新功能的计划。如果你在使用中有合适的想法或建议，也欢迎提出。

后续计划

评论功能在计划之内，目前初步考虑接入 Waline。随笔（essay）的接入相对直接；絮语（bits）是短动态类型的页面，还需要重新设计评论系统在这种页面下的样式与适配方式。因此评论模块虽然已经列入计划，正式上线可能还需要一些时间。

以上内容覆盖了 Content Console 当前的内容管理入口与常用操作。使用中如果遇到内容异常、保存问题，或对功能有想法和建议，都欢迎提交 Issue。