从零造一个机构官网主题(八):从主题到产品——仓库改造、演示站与真实落地
前七篇把主题做出来了。这一篇讲怎么把它变成别人能用的产品:仓库形态改造、演示站怎么用、真实客户站怎么落,以及我做完两套主题后总结的方法论差异。
16 篇文章
前七篇把主题做出来了。这一篇讲怎么把它变成别人能用的产品:仓库形态改造、演示站怎么用、真实客户站怎么落,以及我做完两套主题后总结的方法论差异。
机构官网的客户不会用命令行。所以「部署」必须做到:推到 GitHub 就上线,或者导入仓库点一下就上线。 这一篇把五个平台的配置摊开对比,并讲三个只在平台上才会暴露的坑——它们本地全都是好的。
机构官网的技术栈越简单越好——客户可能三年后才想起改一次,那时框架早就变了。所以整套前端是:一个 610 行的 CSS + 一个 120 行的 JS,零依赖。 这一篇讲这 120 行 JS 里做了什么,以及几个「不用框架也能做得漂亮」的做法。
博客的内容模型很简单:一切都是文章。机构官网不一样——新闻是文章,产品不是,团队不是,案例也不是。如果硬把所有内容塞进文章系统,分类页会变得莫名其妙。 这一篇讲我怎么给三类内容分层,以及踩到的坑。
对博客主题来说,配置是「给开发者的选项」;对机构官网主题来说,配置文件就是客户的操作手册。60+ 项配置写得乱,客户就改不动;改不动,就要来找你。 这一篇讲这套配置怎么分组、怎么保证升级不丢、以及踩到的 YAML 坑。
机构官网的首页是最难做通用的一页:企业要放产品,学校要放师资,政府要放办事入口。如果首页写死成一个模板,这个主题就只能用在一个客户身上。 我的解法是把首页做成一个可编排的数组——layout/index.ejs 只有 7 行。
第一篇说过,三套预设(企业 政务 教育)只换气质不换结构。这一篇讲这个机制具体怎么实现,以及我在「预设该管多少」这件事上反复调整的过程。
做完博客主题 hexo-theme-xfm 之后,我接到了一个完全不同性质的需求:给机构做官网——企业、政务、学校。做完才发现,这两类站点看着都是「一堆网页」,实际是两种物种。 这个系列记录 hexo-theme-xongyi 从零到落地的全过程。它比博客主题更短、更简单,但产品决策的密度更高——因为它的用户不是开发者,是需要自己改文案的客户。
前面七篇都在「加功能」。这一篇讲怎么把主题从「能跑」变成「敢发布」:缺陷怎么治理、移动端那两次诡异故障的真实根因、以及一套让我不再怕发版的工程化流程。
v1.2.0 有两个需求:导航栏加中英切换(要真能用,不能是装饰),以及接入 Google AdSense。前者逼我回答一个架构问题:静态站怎么做语言切换?
写主题时有个很现实的问题:提示块、选项卡、时间轴这些「好看的排版」,官方 Markdown 都不支持。常见做法是装一堆 hexo-tag-* 插件,但那违背了「零第三方依赖」的初衷——而且每装一个,就多一份「升级后不兼容」的风险。 于是我把它们全写进了主题的 scripts/tags/index.js,一共 14 个标签。这一篇讲实现思路和几个必须知道的坑。
第一版的响应式是标准的 @media (max-width: 768px) 三档断点,也能用。但我越用越别扭:手机和桌面共用一套 DOM,只是缩放,形态差异做不出来。 具体痛点是:文档模式在手机上需要「侧栏变抽屉」,在平板上需要「侧栏变折叠面板」,在桌面上才是常驻三栏。这三件事用宽度断点写,会变成一堆互相打架的 @media 补丁。 于是我改成了自适应式响应(adaptive):先识别设备档位,再交付该档专属布局。
三模式听起来像三套模板,实际上只有一个 layout.ejs。所有形态差异都收敛成几个布尔变量,在文件顶部算完,剩下的模板只做「要不要渲染这块」的判断。 这一篇把这段不到 40 行的代码拆开讲——它是整个主题最需要谨慎改动的地方。
主题写到三分之一时我发现一件事:只要有一个组件偷偷写了 #fff,深色模式就永远修不干净。你会在深夜里对着某个灰底白字的卡片怀疑人生,而它的兄弟卡片一切正常。 这一篇讲我用「设计令牌」把这类问题一次性解决的思路——不是理论,是这套主题里真正在跑的分层。
上一篇定了架构,这一篇是动手第一天踩的坑。它们有个共同特点:文档里几乎查不到,报错信息也常常误导,只能靠读 Hexo 源码定位。我把它们按「踩到时的困惑程度」排序,每条都给现象、根因和修法。
市面上的 Hexo 主题并不少,但我还是从零写了一套。不是因为现成的不好,而是因为我的三类内容根本不是同一种东西:博客文章要的是卡片流和挂件栏,笔记要的是能连续翻阅的侧栏树,文档要的是三栏加翻页。用一套博客模板硬套这三种场景,总有一头别扭。 这个系列记录 hexo-theme-xfm 从 efc52bd 首次提交到 v1.3.0 的完整开发过程——包含设计决策、真实代码,以及那些让我调试到怀疑人生的坑。