Hugo on SUUS

使用 TinaCMS 更优雅的管理 Hugo 网站

Fri, 14 Nov 2025 23:53:23 +0800

最近一直在摸索如何在 Hugo 网站上撰写文章，因为我想要一个更方便的写作环境。看到 @佬T博客也一直在折腾如何为 hugo 实现一个方便且快捷的方式来管理文章。我也来了兴趣，于是就想着自己也来试试。

目前我的网站是在本地撰写 markdown ，再推送到 Github ，最后由 Cloudflare 完成线上部署的。这样要撰写文章不方便，因为我得坐在电脑前才能编辑 markdown ，不能随时随地线上编辑修改、发布文章。

有没有我能够直接线上编辑 Github 的 Git 储存库的方式呢？ 「github.dev」 是可以做到，不过我既要又要。像用 WordPress 、 Typecho 等动态网站管理工具一样，直接打开一个网页，登录后台，想改哪篇点哪篇，改完点个「保存」就自动发布，那该多好？

前几天折腾了Netlify CMS ，后台看起来总觉得简陋，本想着将就用吧，但最终还是放弃了，又开始折腾 Front Matter CMS ，随即又发现 Front Matter 的功能只能本地，还不够优雅，终于，找到了一个能实现这个梦想的工具 —— TinaCMS！

啥是 TinaCMS？它能干啥？

简单来说， TinaCMS 是一个开源免费的「无头 CMS」（Headless CMS）。

别被这个名字吓到，「无头」的意思就是它只提供一个内容管理的后台，但不管你的网站「前台」长啥样。这正好跟 Hugo 这种静态网站生成器是天生一对！

装上 TinaCMS 之后，它能帮你在你自己的 Hugo 网站上变出一个管理后台（就像 http://你的网域/admin 这样）。在这个后台里，你可以：

所见即所得地写作： 就像用在线文档一样编辑你的 Markdown 文章。
管理图片： 有个简易的媒体库，上传图片啥的方便多了。
直接改、直接存： 你在后台点「保存」，TinaCMS 就会自动帮你把修改的内容 commit 并 push 到你的 GitHub/GitLab 仓库，触发网站的自动部署。

是不是听起来就很香？

方案一：先在「本地」试试水 (自架模式)

如果你暂时还不想折腾「线上编辑」，只是想在自己电脑上有个更舒服的写作后台（不想天天对着 Markdown ），那可以先试试它的「本地模式」。这个模式下，所有的修改都会直接保存在你电脑上的 Git 仓库里。

开搞步骤：

老规矩使用 IDE 进到你 Hugo 站点文件夹的根目录。
用 npx 安装：（你需要先安装好 NodeJS 和 npm）

npx @tinacms/cli@latest init

安装过程中，它会问你一些问题，记得在「框架」那里选择 Hugo。

改 package.json 文件：安装完后，它会生成一个 package.json。打开它，找到 "scripts" 部分，改成这样：

"scripts": {
  "dev": "tinacms dev -c \"hugo server\"",
  "build": "tinacms build && hugo"
},

这一步是告诉 TinaCMS，在启动开发模式 npm run dev 时，顺便也把 Hugo 的本地预览 hugo server 一并跑起来。

配置 TinaCMS： 这一步最关键。找到 tina/config.ts 这个文件，它会告诉 TinaCMS 你的文章都放在哪个文件夹里。比如，我的文章放在 content/posts 文件夹里，那我就要改成这样：

// tina/config.ts
import { defineConfig } from "tinacms";

export default defineConfig({
  // ... 其他配置 ...
  schema: {
    collections: [
      {
        name: "post", // 类型叫 'post'
        label: "文章", // 后台显示的名称
        path: "content/posts", // 你的 Markdown 文件夹路径！
        fields: [
          {
            type: "string",
            name: "title",
            label: "标题",
            isTitle: true,
            required: true,
          },
          {
            type: "rich-text", // 用富文本编辑器
            name: "body",
            label: "正文",
            isBody: true,
          },
        ],
      },
    ],
  },
});

注意：这里的 path 一定要改成你自己放文章的目录！fields 里的 name 和 label 是你在后台看到的字段名称，isTitle 和 isBody 是告诉 TinaCMS 这个字段是标题和正文。

运行：

npm run dev

等它跑完，打开浏览器，访问 http://localhost:1313/admin/index.html，你就能看到 TinaCMS 的登录界面了！在本地模式下，你在这个后台做的所有修改，都会实时保存在你本地的文件里。恭喜你，你已经成功在本地为 Hugo 搭建了一个无头 CMS！

方案二：终极形态！连上 Tina Cloud

本地玩得差不多了，就该上「重头戏」了——让它连上云（Tina Cloud），实现随时随地线上编辑！

Tina Cloud 是官方提供的一个服务，它充当一个「桥樑」，让你能在网页后台安全地操作你远在 GitHub 上的仓库。

开搞步骤：

注册 Tina Cloud 帐号： 去 TinaCMS 官网注册一个帐号。
授权 GitHub： 登录后，它会引导你连接到你的 GitHub (或 GitLab) 帐号，然后选择你要管理的那个 Hugo 网站仓库。
获取 API Key： 在 Tina Cloud 的项目设置里，你会拿到一串密钥 Client ID 和 Client Secret 。把这些密钥按照官方文档的指示，复制粘贴到你本地的 tina/config.ts 配置文件里。

提示：这些是敏感信息，最好通过 Vercel/Netlify 的「环境变量」来设置，而不是直接写死在代码里再推送到 GitHub 上。

修改「网站部署」指令： 这一步很重要！以前我们部署 Hugo 网站（比如在 Vercel 或 Netlify 上），部署指令可能就是简单的 hugo。现在，因为我们加入了 TinaCMS，所以部署指令要改成 npm run build (就是我们在 package.json 里定义的那个 tinacms build && hugo)。这样，部署平台在打包你的网站时，才会先把 TinaCMS 的后台管理界面也一起打包进去。
推送代码，触发部署： 把你本地修改过的 tina/config.ts、package.json 等文件 git push 到 GitHub。

大功告成！等网站重新部署成功后，你就可以在任何地方，通过访问 https://你的域名/admin/index.html 来登录你的网站后台了！

现在试试看，在后台修改一篇文章并保存。你会发现，过一会儿，你的 GitHub 仓库就多了一个新的 commit，网站也自动开始重新构建了。完美！

实话实说：它有啥缺点？

结合我的经验，TinaCMS 虽好，但目前（特别是对于 Hugo 用户）还有些不完美的地方：

对 Hugo 不算「亲儿子」： 感觉官方的演示和功能重心都在 React 框架 (如 Next.js) 上，对 Hugo 的支持相对弱一些。
编辑器功能一般： 相比一些专门的 Markdown 编辑器，它的后台编辑功能只能算「够用」，不算强大。
本地图片加载： 在本地模式下，加载 Hugo 的本地图片资源可能会有点问题。
搜索功能弱： 后台的文章搜索功能比较拉胯。

总结

总而言之，TinaCMS 给我们这些 Hugo 静态网站的站长提供了一个非常棒的「折中方案」。

它让我们既能享受到静态网站的「快和稳」，又能在一定程度上拥有了像 WordPress 那样「随时随地在线编辑」的便利性。

如果你也受够了繁琐的本地编辑流程，或者想让不懂技术的运营伙伴也能帮你更新网站内容，那么 TinaCMS 绝对值得你花点时间折腾一下！

告别繁琐！用 Front Matter CMS 优雅管理你的静态网站

Thu, 06 Nov 2025 22:03:35 +0000

你是否也觉得静态网站（如 Hugo , Hexo）的文章难以管理？是否也希望有一个漂亮的所见即所得编辑器来辅助写作？

那么，你一定要试试 「Front Matter」 来优雅地管理你的静态网站。

本文将记录我配置 vscode-front-matter 的全过程，并分享配置完成后的“丝滑”发文流程，展示它如何简化操作，提升效率。

Front Matter 的特色功能

「Front Matter」是由 Elio Struyf 开发的一款专为静态网站设计的 CMS (内容管理系统)，它以 Visual Studio Code 扩展的形式提供。

Front Matter 的设计非常灵活，支持多种主流的静态网站生成器：Hugo、Jekyll、Hexo、NextJS、Gatsby、Astro 等。

本文将以 Hugo 为例。我们知道，静态网站的源文件都是由目录和文件组成的。用户常常需要通过命令行，或者直接编辑 Markdown 文件来写作。这对于Geek来说可能不算什么，但对于习惯了 CMS 界面（例如 WordPress）的用户来说，难免会觉得繁琐。

如果能有一款 GUI 工具，或是一个前端界面来编辑 Hugo 网站就好了。

此时，只要装上 Front Matter，你的静态网站写作体验将会轻松许多。Front Matter 让你的 VS Code 仿佛“安装”了一个类似 WordPress 的后台管理界面。结合 VS Code 超强的文字编辑功能，你只需点击几个按钮，就能完成新增文章、预览网站、甚至部署网站等操作。

Front Matter 的核心特色就是图形化。它会自动读取你现有网站的文章、图片、标签、分类，并清晰地罗列在专属面板上。用户可以使用所见即所得的 Markdown 编辑器写作，并通过漂亮的界面来批量管理分类和标签。

Front Matter 甚至还会尝试给出一些 SEO 建议，或者让你调用 AI 来辅助写作。

小小的吐槽： “Front Matter”，作者真是取了个“好”名字。如果搜索时不特别注明，搜到的几乎全是关于 Markdown 语法中 “front matter”（头部元数据）的资料。(黑暗執行緒也认为这个命名不利于 SEO)。

为了清楚地指代，我更喜欢称这个工具为 vscode-front-matter。

当我提到 Front Matter (首字母大写) 时，指的是 vscode-front-matter 这款扩展。

当我提到 front matter (全小写) 时，指的是 Markdown 文件头部的元数据。

为什么你应该使用 Front Matter CMS？

虽然 Hugo 是静态网站框架，但它也可以通过加装外部 CMS，使其拥有后台管理界面。

我这篇文章主要讲的是本地开发的使用情景：即在自己的电脑上安装 VS Code，搭配 Front Matter CMS 来编辑 Hugo 网站的文章。

那么，如果想远程开发呢？如果我们能将网页版的 VS Code (code-server) 部署到 VPS，再在里面安装 Front Matter CMS，理论上就能拥有一个类似 WordPress 后台的在线编辑器。你可以随时随地通过浏览器访问来撰写文章，再也不用盯着一堆 Markdown 文件发愁。

我个人使用 Front Matter 的理由：

我自己想要使用 CMS 的原因是 Hugo 没有像 WordPress 、Typecho 这样的 CMS一样的管理后台。可以很方便地管理分类、标签、图片、文件。

现在，随着文章的增加，难以管理。所以我需要一个更轻松的图形化界面。起码，它可以减少我手动新建文件和目录的步骤，让我能更专注于写作本身。

友情提示

你最好是已经深入使用过 Hugo (或其他静态框架) 一段时间后，再来使用 Front Matter。因为没人比你更清楚你网站的主题结构和工作流。Front Matter 虽然尽力做到了“开箱即用”，但你仍必须按照自己的需求进行调整，才能让它完美契合你的网站。

安装 vscode-front-matter

安装 VS Code，安装 Hugo 和 Git，并确保你的 Hugo 网站项目已建立。

打开 VS Code，点击“文件” → “打开文件夹”，选择你 Hugo 网站的根目录。

在 VS Code 的扩展市场中，搜索并安装 vscode-front-matter。

安装完成后，点击 VS Code 左侧活动栏的 FM 图标，打开 Front Matter 面板，点击 INITIALIZE PROJECT (初始化项目)。

在 FRAMEWORK PRESETS (框架预设) 中选取 hugo。

在 REGISTER CONTENT FOLDERS (注册内容文件夹) 中，选择你存放文章的目录，例如我的是 content 。

点击 IMPORT ALL TAGS AND CATEGORIES (导入所有标签和分类)。

建立 Front Matter 配置文件

请参考 官方文档 进行配置。

注意： 每个 Hugo 主题的设计都不同，你必须根据你的个人情况进行调整。在撰写本文时，我使用的是自己瞎改的主题。

初始化项目后，Front Matter 会在你的网站根目录建立 .vscode 目录和 .frontmatter 目录，以及一个 frontmatter.json 配置文件。

我们只修改 frontmatter.json，不要去动 VS Code 的全局 setting.json。这样，Front Matter 的配置就只在打开这个 Hugo 网站目录时生效。

打开 frontmatter.json，填入以下内容（根据你的情况修改）：

基础预览设置设置网站本地预览地址和 Hugo server 的启动命令。

{
  "frontMatter.preview.host": "http://localhost:1313",
  "frontMatter.site.baseURL": "https://suus.me/",
  "frontMatter.framework.startCommand": "hugo server"
}

内容类型(Content Types)和字段我的文章都是以 Page Bundle 形式发布的。我在 frontMatter.taxonomy.contentTypes 中设置新文章默认包含的 front matter 字段。

{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "default",
      "previewPath": null,
      // 启用 Page Bundle
      "pageBundle": true,
      // 默认新文章目录名，留空，目录就会直接使用文章标题
      "filePrefix": "",
      "fields": [
        {
          "title": "标题",
          "name": "title",
          "type": "string"
        },
        {
          "title": "发布日期",
          "name": "date",
          "type": "datetime",
          "default": "{{now}}",
          "isPublishDate": true
        },
        {
          "title": "是否为草稿",
          "name": "draft",
          "type": "draft"
        },
        {
          "title": "分类",
          "name": "categories",
          "type": "categories"
        },
        {
          "title": "标签",
          "name": "tags",
          "type": "tags"
        },
        {
          "title": "预览图",
          "name": "preview",
          "type": "image"
        }
      ]
    }
  ]
}

Front Matter 和日期格式指定文章 front matter 采用 YAML 格式，并设定时间格式。

{
  "frontMatter.taxonomy.frontMatterType": "YAML",
  "frontMatter.taxonomy.dateFormat": "yyyy-MM-dd'T'HH:mm:ssxxx"
}

注册特定的内容文件夹 (Page Folders) 我的 content 目录下还有不同的 section（如 posts 和 artworks），我使用 frontMatter.content.pageFolders 分别指定它们。

{
  "frontMatter.content.pageFolders": [
    {
      "title": "posts",
      "path": "[[workspace]]/content/posts"
    },
    {
      "title": "artworks",
      "path": "[[workspace]]/content/artworks"
    }
  ]
}

将 Shortcode 转换成 Snippet (代码片段)

我在文章中粘贴 Youtube 视频时，为了避免排版错乱，都用了自定义的 Shortcode 来处理 CSS，但这个代码有点长。

Front Matter 允许你把 Shortcode 短代码变成图形化菜单，以后就可以通过点击按钮来插入。

例如，我有一个 Shortcode 位于 Hugo网站根目录/layouts/shortcodes/embedded-youtube.html。

在文章中插入的语法是： \{\{< embedded-youtube "视频网址"> \}\}

于是，我在 frontmatter.json 中添加以下片段：

{
  // Shortcode 代码片段
  "frontMatter.content.snippets": {
    // "embedded-youtube" 按钮
    "embedded-youtube": {
      "description": "插入 Youtube 视频",
      "body": [
         "{< embedded-youtube [[videourl]] >}"
      ],
      "fields": [
        {
          "name": "videourl",
          "title": "视频网址",
          "type": "string",
          "default": ""
        }
      ]
    }
  },
  // 关闭 Snippet 的默认注释
  "frontMatter.snippets.wrapper.enabled": false
}

配置完成后，Front Matter 的 Dashboard (仪表盘) 上的 Snippets 页面就会出现一个 embedded-youtube 按钮。点击它，填入视频网址，Shortcode 就会自动插入到文章光标处。

一切就绪后的发文流程

配置完成后，我现在的发文流程被极大简化了：

打开 VS Code，打开站点根目录文件夹。切换到 Front Matter (FM) 页面，点击 Create Content (创建内容)。

选择要发布的 section (例如 posts)，输入文章标题。Front Matter 会自动创建好 Page Bundle 目录和 index.md 文件。

插入图片： 点击编辑器右上角的“插入图片”按钮，Front Matter 会自动定位到当前 Page Bundle 所在的目录，我只需选择图片素材即可插入。

优化写作体验： 如果觉得默认编辑器界面不够优雅，可以点击左下角的 Enable writing settings (启用写作设置)，这会临时调整行距和字体，让写作更舒适。

设置缩略图： Front Matter 列表的缩略图需要手动指定才会显示。我依据自己主题的习惯，将 Page Bundle 目录下、与 index.md 同级的 feature.webp 文件设置为文章缩略图 (在 front matter 中指定 preview 字段)。

预览： 在 Dashboard (仪表盘) 点击 Start Server 启动 Hugo 服务器，然后打开浏览器实时预览。

部署： 关于部署，因为我自己准备了一个用于 Git 推送的脚本，所以我没有启用 Front Matter 自带的 Git 集成功能。

关于远程使用 Front Matter

Front Matter 的一个局限在于，它主要还是为本地运行而设计的，对远程开发的支持度不佳，更不用说部署到云平台进行在线编辑了。

如何通过浏览器使用 Front Matter？

如果使用 code-server (网页版 VS Code)，Front Matter 扩展目前无法在浏览器环境中正常运作。

目前可行的方案，也许是连接到电脑的远程桌面，在远程桌面上执行 VS Code 桌面版主程序，这样才能正常使用 Front Matter 的全部功能。