跳转到内容
Home

从hugo迁移至astro

astro astro

前言

Section titled “前言”

Move from hugo to astro. Deploy to cloudflare workers without git.

从wordpress迁移到hugo一周后，我面临了两个难题(折腾的理由)。

不易使用

灵活的使用现代美观的内容不容易

不易修改

模板改起来还是要用前端方法

是的，这是一个mdx文件，上面两张卡片是starlight的内置组件。

import { Card, CardGrid } from '@astrojs/starlight/components';


<CardGrid>
  <Card title="不易使用" icon="open-book">
    灵活的使用现代美观的内容不容易
  </Card>
  <Card title="不易修改" icon="information">
    模板改起来还是要用前端方法
  </Card>
</CardGrid>

用hugo+bootstrap也能实现，方法是shortcode，但是用起来不直观，bootstrap本身也是一个html+css+js的框架。如果要用类似docsy这样的框架，还是需要学习前端的知识，还不如：

尝试

Section titled “尝试”

要上这艘大船真的不容易！（对于没有前端开发经验的人来说）

hugo或zola的逻辑特别简单，尤其是hugo，下载hugo，下载主题，把md文件丢进content目录就可以了。

我用同样的逻辑搞astro，就感觉很不对劲，用老办法（把md丢进content）页面没有反应，日志都列不出来。试图在网络搜索，竟然没有人提到这些看上去很傻很简单的问题。在走了几天弯路之后，硬着头皮去看官方文档(RTFM，根据经验很多问题仔细读文档就能解决)，在学习了官方教程之后，我终于恍然大悟！

hugo视角：网站是一堆素材，而hugo是一个exe二进制工具，能把素材转化成网页，用起来可简可繁，大部分主题只要填充md就能用起来。

Astro视角：网站本质上是一个node项目，而astro是一个node.js包，或者叫框架，并没有内建任何建站规则。所以，需要使用者掌握基础的js项目运行逻辑方可使用。

说人话：astro相对于hugo是手动挡的跑车，而hugo的自动挡也非常好用。哪个更强？我不知道，但开启手动挡的感觉真不错。

为什么简单的问题没有答案，因为astro的大部分开发者和模板提供者都默认使用者具备前端开发能力，没有提供像很多hugo模板的starter解决方案，主题下载之后，需要自己手动修改首页或列表页的逻辑业务代码才能使用，这些问题在开发者看起来太简单了，但对于普通用户真难。这限制了astro的发展，同时创造了商机！我看到有一些网站在提供astro建站服务。

回来说正题，官方教程完整的引导了整个基础网站运行的逻辑，让只会一点html的我也能理解。之后，再使用模板进行修改，就容易的多了！

文档主题能做blog吗？

Section titled “文档主题能做blog吗？”

是的，starlight是一个文档主题，主营业务是docs。

但，她也是astro唯一的官方主题！自带滚动TOC，自带响应式布局（就是手机或电脑能自动调整，不同界面看着都舒服），顶栏侧栏底栏都能定制，自带一些在好用的组件。Lighthouse四个100分！

文档和网志的主要区别：

  1. 文章发表时间的显示；
  2. 前后页面的链接显示；
  3. 侧栏的组织。

这些被starlight-blog插件给解决了，虽然不是很美观，但是随着对astro的熟悉，改起来应该不难。

在hugo的宇宙里，也有类似的docsy。

迁移的过程

Section titled “迁移的过程”

目标还是和之前每次的迁移一样，url需要完整保留，基础功能和文件不丢。

逐步操作

Section titled “逐步操作”

  1. 安装astro和官方主题starlight

    Terminal window
    brew install node
    npm create astro@latest

    第一步选择路径，第二步选择文档主题starlight，github功能我没有用

  2. 安装starlight-blog插件

    npm -i starlight-blog
    npm install
    npm run dev

    这个主题新建站的话特别简单，这里打开浏览器就能看见新站点可以运行了

  3. 填充内容并修改frontmatter

    ./src/content/docs/blog

    如果是新建的站，直接在上述目录下写markdown或mdx即可。

    新写md的frontmatter要注意:

    • 日期date直接按iso格式写，不要加引号
    • 页面地址是slug，不是url，不要用/开头和结尾
    • 封面用cover，和hugo一些主题的feature一样
    • 标签tags和hugo是一样的
    • 文件的引用包括图片，astro要用./astro-logo-dark.png

    如果是迁移的站，把原来的markdown文件丢到blog目录下，然后自行修订上述内容以符合格式。文章多的话，写几个脚本来改，比改插件代码逻辑要快和简单。用ai生成即可，太过简陋这里就不一一贴出来了。

  4. 修改基本设置

    ./astro.config.mjs

  5. 恢复原有url(permlink)

    在astro中，可以在frontmatter中使用slug，和hugo的url效果相同。

    这时候问题来了，因为starlight-blog是一个插件，代码中设置了需要prefix开头才可以识别为blog页面或blog文章页面，我的url大部分都是传统wordpress格式的，比如2004/04/25/why-i-blogging，不符合这个插件的识别规则，直接按文档(docs)渲染，等于跳转到另一个页面了。这需要修改插件中libs/pages.ts。

  6. 修改sidebar

  7. 集成algolia搜索

    astro默认集成的pagefind，中文有问题，集成algolia之后，还是有一些问题（可能是我设置的问题）。

部署至主流静态托管网站

Section titled “部署至主流静态托管网站”

照旧，不用github，直接上传静态目录 启动开发服务器

# 在所有ip地址启动
npm run dev -- --host

测试完成后生成静态网页

npm run build

默认会保存到./dist目录下

  1. vercel

    vercel有点特殊，不能直接上传dist目录，需要用他自己的cli构建并上传，会生成一个.vercel目录，在output目录中保存静态文件。

    # 所有需要选择的设置选默认即可，vercel会自动识别astro项目
    vercel build --prod && vercel deploy --prebuilt --prod

  2. edgeone

    edgeone pages deploy ./dist -n wanglu-site

  3. netlify

    netlify deploy --prod

后记

Section titled “后记”

astro的语法和html类似，使用起来容易，js代码小修小改搭上ai也不难。

网站跑起来很快，在各类设备包括console下都能兼容。

我对starlight主题非常满意，不论在pc、mac、手机、平板，都能恰当、完整、自动的显示所有菜单和内容。

剩余一些不重要的修订，比如tags希望放到右边栏，以后有时间再弄了。

未来一定是靠搜索而不是靠分类或标签，比如algolia就已经很好用了。

补充

Section titled “补充”

starlight-blog以插件的形式实现了blog功能，但同时导致不能使用starlight的override等能力，包括sidebar也不能显式配置了，改起来不是很方便。在ai的加持下，我最后参考了其一部分代码，覆写了两个starlight的组件(Footer, MarkdownContent)，写了两个mdx（首页和allposts页），形成了现在这个blog。

抛弃了前一篇、后一篇的blog常用导航方式；因为搜索的强大，tag和分类目前也没打算再弄。

手动完成这项工作后，对astro的强大和灵活又有了新的认识。

最近更新：

Copyright © 2004-2025 WL