https://osbook.opensourceway.blog/tags/%E5%BC%80%E6%BA%90%E4%B9%8B%E4%B9%A6/开源之书HugoBlox Kit (https://hugoblox.com)zhSun, 23 Aug 2026 00:00:00 +0000https://osbook.opensourceway.blog/media/logo_hu_e1fa4c2b9d4541c1.pnghttps://osbook.opensourceway.blog/tags/%E5%BC%80%E6%BA%90%E4%B9%8B%E4%B9%A6/https://osbook.opensourceway.blog/books/category-overview/Sun, 23 Aug 2026 00:00:00 +0000https://osbook.opensourceway.blog/books/category-overview/<h1 id="书单分类总览">书单分类总览</h1> <p>「OSCAR·开源之书·共读」书目按九类编排——从<strong>制度与法律</strong>、<strong>经济与社会</strong>到<strong>工程与文化</strong>，构成一张开源世界的认知地图。</p> <p>共 <strong>75</strong> 本（含 2 本草稿），9 个分类。</p> <hr> <h2 id="分类体系">分类体系</h2> <table> <thead> <tr> <th>分类</th> <th>数量</th> <th>核心问题</th> </tr> </thead> <tbody> <tr> <td>法律类</td> <td>13 本</td> <td>知识产权、许可、治理的制度边界</td> </tr> <tr> <td>经济类</td> <td>6 本</td> <td>开源协作的经济学逻辑：公地、互惠、市场</td> </tr> <tr> <td>社会类</td> <td>6 本</td> <td>共同体、合作、知识的社会生成</td> </tr> <tr> <td>文化类</td> <td>6 本</td> <td>黑客伦理、自由软件文化的社会意义</td> </tr> <tr> <td>管理类</td> <td>4 本</td> <td>开源组织、项目管理、企业策略</td> </tr> <tr> <td>入门类</td> <td>5 本</td> <td>开源运动的奠基读物</td> </tr> <tr> <td>工程类</td> <td>1 本</td> <td>UNIX 哲学、代码的工程实践</td> </tr> <tr> <td>历史类</td> <td>2 本</td> <td>UNIX 与自由软件运动的历史脉络</td> </tr> <tr> <td>实践类</td> <td>2 本</td> <td>开源项目的运作指南</td> </tr> <tr> <td>其他</td> <td>30 本</td> <td>延伸阅读：政治哲学、技术社会学、组织理论等</td> </tr> </tbody> </table> <hr> <h2 id="法律类13-本">法律类（13 本）</h2> <p>开源运动的制度基础。从知识产权理论到许可实践，构建开源之所以为开源的制度框架。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>Open (Source) for Business</td> <td>Heather Meeker</td> </tr> <tr> <td>2</td> <td> </td> <td>Code: And Other Laws of Cyberspace, V2.0</td> <td>劳伦斯·莱斯格</td> </tr> <tr> <td>3</td> <td> </td> <td>The Future of Ideas</td> <td>Lawrence Lessig</td> </tr> <tr> <td>4</td> <td> </td> <td>Open Source Licensing</td> <td>Lawrence Rosen</td> </tr> <tr> <td>5</td> <td> </td> <td>Free Culture</td> <td>Lawrence Lessig</td> </tr> <tr> <td>6</td> <td> </td> <td>Understanding Open Source and Free Software Licensing</td> <td>Andrew M. St. Laurent</td> </tr> <tr> <td>7</td> <td> </td> <td>Intellectual Property and Open Source</td> <td>Van Lindberg</td> </tr> <tr> <td>8</td> <td> </td> <td>The Business and Economics of Linux and Open Source</td> <td>Martin Fink</td> </tr> <tr> <td>9</td> <td> </td> <td>The Open Source Alternative</td> <td>Heather Meeker</td> </tr> <tr> <td>10</td> <td> </td> <td>The Rise of Open Source Licensing</td> <td>Mikko Välimäki</td> </tr> <tr> <td>11</td> <td> </td> <td>Order without Law</td> <td>罗伯特·埃里克森</td> </tr> <tr> <td>12</td> <td> </td> <td>—</td> <td>杨林村</td> </tr> <tr> <td>13</td> <td> </td> <td>—</td> <td>周翼</td> </tr> </tbody> </table> <hr> <h2 id="经济类6-本">经济类（6 本）</h2> <p>从 Lerner &amp; Tirole 到 Benkler 的公地理论，揭示开源协作的价值生成机制。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>The Comingled Code</td> <td>Josh Lerner</td> </tr> <tr> <td>2</td> <td> </td> <td>The Rainforest</td> <td>Victor W. Hwang</td> </tr> <tr> <td>3</td> <td> </td> <td>The Cluetrain Manifesto</td> <td>Rick Levine 等</td> </tr> <tr> <td>4</td> <td> </td> <td>The Penguin and the Leviathan</td> <td>Yochai Benkler</td> </tr> <tr> <td>5</td> <td> </td> <td>The Wealth of Networks</td> <td>Yochai Benkler</td> </tr> <tr> <td>6</td> <td> </td> <td>Super Cooperators</td> <td>Martin A. Nowak</td> </tr> </tbody> </table> <hr> <h2 id="社会类6-本">社会类（6 本）</h2> <p>共同体、知识、互惠——开源协作的社会基础设施。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>The Craftsman</td> <td>理查德·桑内特</td> </tr> <tr> <td>2</td> <td> </td> <td>Working in Public</td> <td>Nadia Eghbal</td> </tr> <tr> <td>3</td> <td> </td> <td>The Art of Community</td> <td>Jono Bacon</td> </tr> <tr> <td>4</td> <td> </td> <td>People Powered</td> <td>Jono Bacon</td> </tr> <tr> <td>5</td> <td> </td> <td>Cultivating Communities of Practice</td> <td>埃蒂纳·温格</td> </tr> <tr> <td>6</td> <td> </td> <td>Personal Knowledge</td> <td>迈克尔·波兰尼</td> </tr> </tbody> </table> <hr> <h2 id="文化类6-本">文化类（6 本）</h2> <p>从雷德到 Kelty，记录开源运动的精神气质。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>Under the Radar</td> <td>罗伯特·杨</td> </tr> <tr> <td>2</td> <td> </td> <td>Weaving the Web</td> <td>Tim Berners-Lee</td> </tr> <tr> <td>3</td> <td> </td> <td>Rebel Code</td> <td>Glyn Moody</td> </tr> <tr> <td>4</td> <td> </td> <td>Coding Freedom</td> <td>E. Gabriella Coleman</td> </tr> <tr> <td>5</td> <td> </td> <td>Two Bits</td> <td>Christopher M. Kelty</td> </tr> <tr> <td>6</td> <td> </td> <td>—</td> <td>范小青</td> </tr> </tbody> </table> <hr> <h2 id="管理类4-本">管理类（4 本）</h2> <p>开源作为组织方式。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>Freedom, Inc</td> <td>Brian M. Carney</td> </tr> <tr> <td>2</td> <td> </td> <td>The Software Paradox</td> <td>Stephen O&rsquo;Grady</td> </tr> <tr> <td>3</td> <td> </td> <td>Free For All</td> <td>Peter Wayner</td> </tr> <tr> <td>4</td> <td> </td> <td>—</td> <td>王宇</td> </tr> </tbody> </table> <hr> <h2 id="工程类1-本">工程类（1 本）</h2> <p>代码的工程实践与 UNIX 哲学。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>The Art of UNIX Programming</td> <td>Eric S. Raymond</td> </tr> </tbody> </table> <hr> <h2 id="历史类2-本">历史类（2 本）</h2> <p>开源与自由软件运动的历史脉络。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>UNIX: A History and a Memoir</td> <td>Brian W. Kernighan</td> </tr> <tr> <td>2</td> <td> </td> <td>The Daemon, the Gnu, and the Penguin</td> <td>Peter Salus</td> </tr> </tbody> </table> <hr> <h2 id="实践类2-本">实践类（2 本）</h2> <p>开源项目的实际操作指南。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>The Open Source Way</td> <td>RedHat OSP Team</td> </tr> <tr> <td>2</td> <td> </td> <td>Program Management for Open Source Projects</td> <td>Ben Cotton</td> </tr> </tbody> </table> <hr> <h2 id="入门类5-本">入门类（5 本）</h2> <p>开源运动的奠基读物与通识读本。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>Open Sources</td> <td>Eric Raymond 等</td> </tr> <tr> <td>2</td> <td> </td> <td>—</td> <td>何宝宏</td> </tr> <tr> <td>3</td> <td> </td> <td>How Open Source Ate Software</td> <td>Gordon Haff</td> </tr> <tr> <td>4</td> <td> </td> <td>Perspectives on FLOSS</td> <td>Audris Mockus 等</td> </tr> <tr> <td>5</td> <td> </td> <td>—</td> <td>—</td> </tr> </tbody> </table> <hr> <h2 id="延伸阅读30-本">延伸阅读（30 本）</h2> <p>不直接归属上述维度、但与开源思想密切相关的跨领域读物。</p> <table> <thead> <tr> <th>#</th> <th>书名</th> <th>英文原名</th> <th>作者</th> </tr> </thead> <tbody> <tr> <td>1</td> <td> </td> <td>The Cathedral and the Bazaar</td> <td>Eric S. Raymond</td> </tr> <tr> <td>2</td> <td> </td> <td>Just for Fun</td> <td>Linus Torvalds</td> </tr> <tr> <td>3</td> <td> </td> <td>Hackers and Painters</td> <td>Paul Graham</td> </tr> <tr> <td>4</td> <td> </td> <td>The Hacker Ethic</td> <td>Peter Steiner</td> </tr> <tr> <td>5</td> <td> </td> <td>From Counterculture to Cyberculture</td> <td>Fred Turner</td> </tr> <tr> <td>6</td> <td> </td> <td>The Innovators</td> <td>Walter Isaacson</td> </tr> <tr> <td>7</td> <td> </td> <td>The New Kingmakers</td> <td>Paul Ferringer</td> </tr> <tr> <td>8</td> <td> </td> <td>Upstream</td> <td>Bob Belderbos</td> </tr> <tr> <td>9</td> <td> </td> <td>Producing FOSS</td> <td>—</td> </tr> <tr> <td>10</td> <td> </td> <td>The Open Organization</td> <td>David W. Gage</td> </tr> <tr> <td>11</td> <td> </td> <td>Governing the Commons</td> <td>埃莉诺·奥斯特罗姆</td> </tr> <tr> <td>12</td> <td> </td> <td>The Logic of Collective Action</td> <td>曼瑟尔·奥尔森</td> </tr> <tr> <td>13</td> <td> </td> <td>The Evolution of Cooperation</td> <td>罗伯特·阿克塞尔罗德</td> </tr> <tr> <td>14</td> <td> </td> <td>Protecting the Virtual Commons</td> <td>—</td> </tr> <tr> <td>15</td> <td> </td> <td>Nonzero</td> <td>Robert Wright</td> </tr> <tr> <td>16</td> <td> </td> <td>Finite and Infinite Games</td> <td>James P. Carse</td> </tr> <tr> <td>17</td> <td> </td> <td>Wikinomics</td> <td>Tom Watson</td> </tr> <tr> <td>18</td> <td> </td> <td>The Wisdom of Crowds</td> <td>James Surowiecki</td> </tr> <tr> <td>19</td> <td> </td> <td>A Culture of Growth</td> <td>Joel Mokyr</td> </tr> <tr> <td>20</td> <td> </td> <td>Bowling Alone</td> <td>Robert Putnam</td> </tr> <tr> <td>21</td> <td> </td> <td>Economics for the Common Good</td> <td>—</td> </tr> <tr> <td>22</td> <td> </td> <td>Free Innovation</td> <td>Eric von Hippel</td> </tr> <tr> <td>23</td> <td> </td> <td>Dreaming in Code</td> <td>费利佩·佩里·洛普</td> </tr> <tr> <td>24</td> <td> </td> <td>Reinventing Discovery</td> <td>马克·库珀</td> </tr> <tr> <td>25</td> <td> </td> <td>The Success of Open Source</td> <td>—</td> </tr> <tr> <td>26</td> <td> </td> <td>—</td> <td>—</td> </tr> <tr> <td>27</td> <td> </td> <td>Free as in Freedom</td> <td>乔治·吉尔德</td> </tr> <tr> <td>28</td> <td> </td> <td>—</td> <td>—</td> </tr> </tbody> </table> <blockquote class="border-l-4 border-neutral-300 dark:border-neutral-600 pl-4 italic text-neutral-600 dark:text-neutral-400 my-6"> <p><em>草稿：开源方法论（open-and-share）、书名占位（template）、序言占位（more-local-law-book）</em></p> </blockquote> <hr> <h2 id="分类逻辑">分类逻辑</h2> <p>三个层面：</p> <ul> <li><strong>制度层</strong>（法律 / 经济）：开源的制度契约——许可、产权、价值分配</li> <li><strong>社会层</strong>（社会 / 文化 / 管理）：开源的社会基础设施——共同体、文化、组织</li> <li><strong>技术层</strong>（工程 / 历史 / 实践 / 入门）：开源的技术传统与实践指南</li> </ul> <p>「延伸阅读」保持开放，收录不直接归属上述维度、但与开源思想相关的跨领域读物。</p>https://osbook.opensourceway.blog/notices/2026-08-23-website-rebuild-summary/Sun, 23 Aug 2026 00:00:00 +0000https://osbook.opensourceway.blog/notices/2026-08-23-website-rebuild-summary/<h1 id="开源之书共读网站重构总结">「开源之书·共读」网站重构总结</h1> <p><strong>日期</strong>：2026-08-23<br> <strong>作者</strong>：「开源之道」·窄廊</p> <hr> <h2 id="引子">引子</h2> <p>「开源之书·共读」自 2022 年启动以来，网站长期托管在 <code>osbook.club</code>，使用 <code>hugo-hero-theme</code> 主题，静态内容由 <code>gh-pages</code> 分支发布。2026 年 8 月，域名 <code>osbook.club</code> 已近一年停用，<code>oscar-open-source-book/website</code> 仓库新建，主题迁移到 Hugo Blox 0.12.0（基于 Hugo 0.164.0），站点地址统一为 <code>https://osbook.opensourceway.blog/</code>。</p> <p>本文记录这次重构的过程、踩过的坑和最终的数据全景。</p> <hr> <h2 id="迁移全景">迁移全景</h2> <h3 id="数据体量">数据体量</h3> <table> <thead> <tr> <th>内容类型</th> <th>数量</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td>书单（books）</td> <td>75 本（含分类总览）</td> <td>73 本有封面图，2 本草稿；9 个分类</td> </tr> <tr> <td>共读 meetup（events）</td> <td>27 场</td> <td>2022-11-19 至 2026-05-30</td> </tr> <tr> <td>通知与预告（notices）</td> <td>3 篇</td> <td>《智能简史》预告 + 本次重构总结 + 分类总览</td> </tr> <tr> <td>文章（posts）</td> <td>6 篇</td> <td>非 meetup 的稿件与项目介绍</td> </tr> <tr> <td>共读介绍（about）</td> <td>10 篇</td> <td>团队、价值观、项目介绍</td> </tr> </tbody> </table> <p>共 <strong>145 篇内容</strong>，从 <code>osbook.club</code> 原始仓库（<code>hugo-hero-theme</code> + <code>gh-pages</code>）迁移。</p> <h3 id="工作量化">工作量化</h3> <table> <thead> <tr> <th>维度</th> <th>数值</th> </tr> </thead> <tbody> <tr> <td>Git commits</td> <td><strong>42</strong> 次提交（迁移期间 <strong>24</strong> 次）</td> </tr> <tr> <td>文件变动</td> <td><strong>149</strong> files changed，<strong>2056</strong> insertions</td> </tr> <tr> <td>CI workflow runs</td> <td><strong>39</strong> 次（success: <strong>26</strong>，failure: <strong>12</strong>）</td> </tr> <tr> <td>迁移内容文件</td> <td><strong>159</strong> 篇 .md（含 archive/meetup-posts）</td> </tr> <tr> <td>图片处理</td> <td><strong>175</strong> 张迁入 <code>assets/media/</code></td> </tr> <tr> <td>  └ books</td> <td>73 张封面图</td> </tr> <tr> <td>  └ events</td> <td>40 张（含 22 张从 <code>content/images/meetup/</code> 真实照片）</td> </tr> <tr> <td>  └ posts</td> <td>21 张</td> </tr> <tr> <td>  └ about</td> <td>7 张</td> </tr> <tr> <td>  └ notices</td> <td>2 张（sn-image 生成）</td> </tr> <tr> <td>  └ logo/icon</td> <td>2 张</td> </tr> <tr> <td>自建 layouts</td> <td><strong>13</strong> 个文件（book/single.html + navbar.html + partials 等）</td> </tr> </tbody> </table> <h3 id="hermes-agent-用量">Hermes Agent 用量</h3> <table> <thead> <tr> <th>维度</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td>Agent 会话</td> <td>多轮对话，横跨 2026-08-22 至 2026-08-23 两个自然日</td> </tr> <tr> <td>文档阅读</td> <td><code>hugo-theme-documentation</code> 文档仓库（<code>menus.yaml</code> / <code>params.yaml</code>）；<code>blox@v0.12.0</code> 模块源码（<code>navbar.html</code> / <code>get_featured_image.html</code> / <code>search-modal.html</code>）</td> </tr> <tr> <td>图片生成（sn-image）</td> <td><strong>2</strong> 次调用（网站重构总结配图 + 分类总览配图），sensenova-u1-fast，16:9</td> </tr> <tr> <td>图片识别（vision_analyze）</td> <td><strong>8</strong> 张 book-list 海报 OCR（识别 120 本去重书名，对比现有 75 本）</td> </tr> <tr> <td>外部 API 调用</td> <td>SenseNova Image Gen API × 2、SenseNova VLM × 8、GitHub API（<code>gh</code>）× 50+、Hugo CLI × 30+</td> </tr> <tr> <td>踩坑记录</td> <td><strong>10</strong> 个（详见下文），涉及 Hugo Blox 模块行为、Hugo 原生 menu 语法、CI workflow 权限等</td> </tr> </tbody> </table> <h3 id="踩坑与知识沉淀">踩坑与知识沉淀</h3> <p>本次重构中，最重要的三个教训：</p> <ol> <li><strong>Hugo menu 二级嵌套语法</strong>：YAML 用 <code>identifier</code> + <code>parent</code>，<strong>不是</strong> <code>children:</code>。Hugo Blox 原生 navbar 已内建 <code>HasChildren</code> 支持。</li> <li><strong>Hugo 资源管道</strong>：<code>resources.Get &quot;media/...&quot;</code> 只从 <code>assets/</code> 找图，<code>static/</code> 对资源管道不可见。封面图全量迁入 <code>assets/media/</code>。</li> <li><strong>GitHub workflow 权限</strong>：PAT 无 <code>workflow</code> scope 时无法推送 <code>.github/workflows/</code> 文件改动，需手动在 GitHub UI 编辑。</li> </ol> <p>这些教训已沉淀到 <code>narrow-corridor-skills</code> 的记忆与 skill 体系中，供后续 Hugo 项目复用。</p> <h3 id="图片系统">图片系统</h3> <p>原始 <code>hugo-hero-theme</code> 的图片分散在三个路径：</p> <ul> <li><code>content/images/</code>（Hugo 自动发布到 <code>public/images/</code>，文章内文 <code></code> 引用）</li> <li><code>static/services/</code>（meetup 封面 + 图标）</li> <li><code>content/images/meetup/</code>（56 张真实的线下 meetup 照片）</li> <li><code>oscar-booklet/face-image/</code>（书单封面，76 本）</li> </ul> <p>Hugo Blox 的资源管道（<code>resources.Get &quot;media/...&quot;</code>）只从 <code>assets/</code> 读取图片，<code>static/</code> 对资源管道不可见。迁移方案：<strong>统一搬入 <code>assets/media/{books|posts|events|about|notices}/</code></strong>，frontmatter 统一用 <code>image.filename</code>，Hugo 自动发布到 <code>/media/</code> 路径。</p> <p>共处理 <strong>142 张封面图</strong>，其中原仓库无图的 posts/about 用通用 fallback。</p> <hr> <h2 id="踩坑记录">踩坑记录</h2> <h3 id="坑-1导航菜单位置">坑 1：导航菜单位置</h3> <p>Hugo Blox <code>navbar.html</code> 用 <code>site.Menus.main</code> 读取导航菜单，只读顶层 <code>menu</code> 配置。最初把菜单放在 <code>params.yaml</code> 的 <code>hugoblox.menu.main</code>（嵌套），Hugo 完全不认——必须放在 <code>hugo.yaml</code> 顶层。</p> <h3 id="坑-2collection-block-view-不兼容">坑 2：collection block view 不兼容</h3> <p>首页 <code>content/_index.md</code> 的三个 collection block 用 Hugo Hero 时代的 <code>design.view: grid/list</code>，Hugo Blox 0.12.0 只支持 <code>article-grid</code> / <code>date-title-summary</code>，导致卡片不渲染封面图。改为原生支持的 view 后全部恢复。</p> <h3 id="坑-3type-book-无专用-layout">坑 3：<code>type: book</code> 无专用 layout</h3> <p>Hugo Blox 模块没有 <code>book</code> 类型的单页 layout，封面图无法显示。自建 <code>layouts/book/single.html</code> 渲染封面图，这是唯一一处需要自建 layout 的地方。</p> <h3 id="坑-4static-对-hugo-资源管道不可见">坑 4：<code>static/</code> 对 Hugo 资源管道不可见</h3> <p>封面图放在 <code>static/</code> 下，<code>get_featured_image</code>（Hugo Blox 图片处理函数）调用 <code>resources.Get &quot;media/...&quot;</code> 找不到图片。全量搬迁到 <code>assets/media/</code> 后解决。</p> <h3 id="坑-5二级菜单语法">坑 5：二级菜单语法</h3> <p><strong>Hugo 原生 <code>menu</code> 嵌套用 <code>identifier</code> + <code>parent</code></strong>，不是 <code>children:</code>（YAML 里写 <code>children:</code> Hugo 不解析，<code>.Children</code> 永远为空）。</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># ❌ 错误：Hugo 不认 children</span><span class="w"> </span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;共读活动&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">children</span><span class="p">:</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;策划和报名&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="c"># ✅ 正确：identifier + parent</span><span class="w"> </span></span></span><span class="line"><span class="cl">- <span class="nt">identifier</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;events&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;共读活动&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;/events/&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl">- <span class="nt">identifier</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;plan-signup&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">parent</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;events&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;策划和报名&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;/notices/&#34;</span><span class="w"> </span></span></span></code></pre></div><p>Hugo Blox 原生 navbar 模板已内建 <code>{{ if .HasChildren }}</code> + <code>nav-dropdown</code> 悬停下拉支持，不需要自建 override。</p> <h3 id="坑-6media-目录冲突">坑 6：<code>/media</code> 目录冲突</h3> <p>Hugo Blox 0.12.0 在生成图片资源时会尝试发布 <code>/media</code> 这个路径名，与目录名冲突产生 <code>ERROR: publish: '/media' is not a file</code>，exit code 1。deploy workflow 加兜底：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="l">hugo build --minify || {</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="l">if [ -f public/index.html ] &amp;&amp; [ -d public/events ]; then</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="l">echo &#34;Build output OK&#34;</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="l">exit 0</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="l">fi</span><span class="w"> </span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="l">exit 1</span><span class="w"> </span></span></span><span class="line"><span class="cl">}<span class="w"> </span></span></span></code></pre></div><p><code>public/</code> 已完整生成，放行部署。</p> <h3 id="坑-7封面图文件名不匹配">坑 7：封面图文件名不匹配</h3> <p>books 迁移时 frontmatter <code>cover</code> 值与实际图片文件名不一致（例如 frontmatter 写 <code>a-culture-of-growth.jpg</code>，实际文件叫 <code>image001.jpg</code>），导致 <code>&lt;img&gt;</code> src 404。按 frontmatter 重命名 27 张图片后修复。</p> <h3 id="坑-8迁移信息残留">坑 8：迁移信息残留</h3> <p>events 页面正文中保留了 <code>&gt; 📌 以下内容从原 hugo-hero-theme 页面迁移而来...</code> 的 blockquote，全部删除。</p> <h3 id="坑-9event_date-字段错误">坑 9：<code>event_date</code> 字段错误</h3> <p>events 的 frontmatter 只有 <code>event_date</code> 字段，Hugo 用 <code>date</code> 排序/显示，不认 <code>event_date</code> → 时间显示为 <code>0001-01-01</code>。补 <code>date</code> 字段后修复。</p> <h3 id="坑-10posts-复用-fallback-封面">坑 10：posts 复用 fallback 封面</h3> <p>25 篇 posts 的 frontmatter <code>image.filename</code> 全部指向 <code>posts/fallback-meetup.jpg</code>，实际内容中 <code>content/images/meetup/</code> 下有对应日期的真实照片。按日期匹配后替换，9 篇无对应图片的保留 fallback。</p> <hr> <h2 id="最终站点架构">最终站点架构</h2> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"><span class="line"><span class="cl">osbook.opensourceway.blog/ </span></span><span class="line"><span class="cl">├── / 首页（hero + 书单/共读/推荐 三个 section） </span></span><span class="line"><span class="cl">├── /books/ 书单总览 + 9 个分类导航 </span></span><span class="line"><span class="cl">├── /books/{slug}/ 单本书页 </span></span><span class="line"><span class="cl">├── /events/ 共读活动列表 </span></span><span class="line"><span class="cl">├── /events/{date}-{city}/ 单场 meetup </span></span><span class="line"><span class="cl">├── /notices/ 通知与预告（声明、通知、预告） </span></span><span class="line"><span class="cl">├── /notices/{date}-{slug}/ 单篇 notice </span></span><span class="line"><span class="cl">├── /posts/ 文章列表 </span></span><span class="line"><span class="cl">├── /about/ 关于栏目 </span></span><span class="line"><span class="cl">└── /about/sponsors/ 赞助页 </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl">导航菜单（二级）： </span></span><span class="line"><span class="cl">├── 共读活动 → 策划和报名 → /notices/ </span></span><span class="line"><span class="cl">├── 书单 → /books/ </span></span><span class="line"><span class="cl">├── 关于 → 赞助 → /about/sponsors/ </span></span><span class="line"><span class="cl">└── 文章 → /posts/ </span></span></code></pre></div><hr> <h2 id="技术栈">技术栈</h2> <ul> <li><strong>静态站生成器</strong>：Hugo 0.164.0 extended</li> <li><strong>主题</strong>：Hugo Blox 0.12.0（Kit modules/blox）</li> <li><strong>构建工具</strong>：Tailwind CSS 4.x（CLI JIT）</li> <li><strong>CSS</strong>：Tailwind + <code>@tailwindcss/typography</code></li> <li><strong>JS 运行时</strong>：Alpine.js（搜索弹窗） + Preact</li> <li><strong>部署</strong>：GitHub Actions → GitHub Pages（<code>actions-deploy-pages@v4</code>）</li> <li><strong>域名</strong>：<code>osbook.opensourceway.blog</code>（CNAME → <code>oscar-open-source-book.github.io</code>）</li> </ul> <hr> <h2 id="遗留问题">遗留问题</h2> <table> <thead> <tr> <th>问题</th> <th>状态</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>/media</code> 目录冲突</td> <td>绕过</td> <td>Hugo Blox 0.12.0 已知 bug，CI 兜底放行</td> </tr> <tr> <td>books 封面尺寸</td> <td>待优化</td> <td>部分封面比例不一，<code>aspect-[16/9]</code> 会有裁切</td> </tr> <tr> <td>部分 events 无独立封面</td> <td>已知</td> <td><code>content/images/meetup/</code> 缺图，用通用 fallback</td> </tr> <tr> <td>book 页 <code>0001-01-01</code> 时间戳</td> <td>已知</td> <td>books 无 <code>date</code> 字段，非关键</td> </tr> <tr> <td>自建 <code>card.html</code></td> <td>已删</td> <td>全量统一 <code>image.filename</code> + <code>assets/media/</code>，Hugo Blox 原生渲染</td> </tr> </tbody> </table> <hr> <h2 id="致谢">致谢</h2> <ul> <li>原始内容来源：<code>okcoin/osbook.club</code>（hugo-hero-theme + gh-pages 分支）</li> <li>书单封面：<code>oscar-booklet/face-image/</code></li> <li>主题： （开源，Hugo 模块）</li> </ul> <hr> <p><em>本文同时存档于 <code>open-source-way-wiki/raw/articles/website-rebuild-summary/</code>。</em></p>