博客主题由极简的 M10c 迁移到结构复杂的 Stack

2025-12-26

博客主题由极简的 M10c 迁移到结构复杂的 Stack

第一步备份

最稳妥的备份方案：Git 分支法

既然你已经用了 Git，不需要手动复制文件夹。利用 Git 的分支功能是专业且最高效的备份方式。

# 1. 确保当前代码已全部提交
git add .
git commit -m "Backup before switching to Stack"

# 2. 创建一个名为 'm10c-version' 的备份分支
git branch m10c-version
git push origin m10c-version

# 3. 此时你可以放心在 main 分支折腾。
# 如果折腾坏了，随时可以用下面这行命令秒回原始状态：
# git reset --hard m10c-version

第二步切换到主分支准备“动刀”

确保你现在处于 main 分支上（备份分支留在原地不动，作为“救命稻草”）：

git checkout main

第三步：清理旧主题并添加新主题

在 Windows 上正确移除旧主题请在项目根目录按顺序执行以下命令：

从 Git 中移除子模块记录

git rm -r themes/hugo-theme-m10c

手动删除残留文件夹（如果报错说目录不存在可以忽略）

rd /s /q themes\hugo-theme-m10c

在添加新主题之前，建议先提交一次，保持 Git 记录清晰：

git add .
git commit -m "Remove old m10c theme"

重新添加 Stack 主题现在可以干净地添加新主题了：

git submodule add https://github.com/CaiJimmy/hugo-theme-stack themes/hugo-theme-stack

第四步：复制示例配置文件

Stack 主题的功能非常多，手动写 hugo.toml 很容易出错。建议直接从主题目录拷贝官方提供的示例配置：

1. 在你的项目根目录找到 `themes/hugo-theme-stack/exampleSite`。

2. 将其中的 `hugo.yaml` (或 `config.yaml`) 拷贝到你的根目录，并替换掉你原本的 `hugo.toml`。

注意：Stack 默认使用 YAML 格式配置。如果你习惯 TOML，需要手动转换，但我建议直接跟从作者使用 hugo.yaml。

3. 调整文件夹结构

Stack 主题需要一些特殊的页面来支撑它的功能（如搜索、归档、关于）：

复制资源文件：将 themes/hugo-theme-stack/exampleSite/content 下的 page 文件夹拷贝到你自己的 content/ 目录下。
- 这个 page 文件夹里通常包含 archives.md (归档) 和 search.md (搜索)。
文章目录：确保你的文章都在 content/post/ 目录下（Stack 默认识别 post 而不是 posts，你可以在配置文件中修改）。
m10c 比较简单，但 Stack 增加了一些视觉元素。建议在你的旧文章头部（Front Matter）添加以下字段：

image= "https://bed.886423.xyz/file/1766555872266_11.jpg"

针对你之前的 GitHub Actions 部署优化因为 Stack 依赖 Hugo 的一些高级功能，请确保你的 .github/workflows/deploy.yml 中的 Hugo 设置如下：

Extended 版本：Stack 使用了 SCSS，必须开启 extended: true。
Hugo 版本：建议指定一个较新版本（如 0.120.0 以上）。

- name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.125.0' # 建议明确版本
          extended: true         # 必须为 true

:smile:

4. 美好和定制

修改配置文件hugo.yaml

baseurl: https://example.com/
languageCode: zh-cn
theme: hugo-theme-stack
title: 博士日常
copyright: BoSh

# Theme i18n support
# Available values: ar, bn, ca, de, el, en, es, fr, hu, id, it, ja, ko, nl, pt-br, th, uk, zh-cn, zh-hk, zh-tw
DefaultContentLanguage: zh-cn
# 禁用多语言功能，防止生成 /zh-cn/ 这样的子目录
disableLanguages: ["en", "es"]

# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh-cn ja ko]
# This will make .Summary and .WordCount behave correctly for CJK languages.
hasCJKLanguage: false

languages:
    
    zh-cn:
        languageName: 简体中文
        title: 博士日常
        weight: 1
        params:
            sidebar:
                subtitle: 记录生活 分享知识

    

services:
    # Change it to your Disqus shortname before using
    disqus:
        shortname: "hugo-theme-stack"
    # GA Tracking ID
    googleAnalytics:
        id:

pagination:
    pagerSize: 3

permalinks:
    post: /p/:slug/
    page: /:slug/

params:
    mainSections:
        - post
    featuredImageField: image
    rssFullContent: true
    favicon: # e.g.: favicon placed in `static/favicon.ico` of your site folder, then set this field to `/favicon.ico` (`/` is necessary)

    footer:
        since: 2025
        customText: 热爱生活 学无止境 

    dateFormat:
        published: Jan 02, 2006
        lastUpdated: Jan 02, 2006 15:04 MST

    sidebar:
        emoji: 😍
        subtitle: 终身学习者 / 开发者
        avatar:
            enabled: true
            local: false
            src: img/avatar.png

    article:
        math: false
        toc: true
        readingTime: true        
        license:
            enabled: true
            default: Licensed under CC BY-NC-SA 4.0

    
    widgets:
        homepage:
            - type: search
            - type: archives
              params:
                  limit: 5
            - type: categories
              params:
                  limit: 10
            - type: tag-cloud
              params:
                  limit: 10
        page:
            - type: toc

    opengraph:
        twitter:
            # Your Twitter username
            site:

            # Available values: summary, summary_large_image
            card: summary_large_image

    defaultImage:
        opengraph:
            enabled: false
            local: false
            src:

    colorScheme:
        # Display toggle
        toggle: true

        # Available values: auto, light, dark
        default: auto

    imageProcessing:
        cover:
            enabled: true
        content:
            enabled: true

### Custom menu
### See https://stack.jimmycai.com/config/menu
### To remove about, archive and search page menu item, remove `menu` field from their FrontMatter
# 找到原来的 menu 部分并替换成这样：
menu:
    main:
        - identifier: home
          name: 首页
          url: /
          weight: -100
          params:
              icon: home


    social:
        
              
        - identifier: vercel-blog
          name: BLOG ON Vercel
          url: https://886423.xyz
          params:
              icon: link # 改为 link
              
        - identifier: github
          name: GitHub
          url: https://github.com/zhisibi
          params:
              icon: brand-github      
              
        - identifier: vps-blog
          name: BLOG ON VPS
          url: https://bosh.zz.ac
          params:
              icon: link # 
    
            

related:
    includeNewer: true
    threshold: 60
    toLower: false
    indices:
        - name: tags
          weight: 100

        - name: categories
          weight: 200

markup:
    goldmark:
        extensions:
            passthrough:
                enable: true
                delimiters:
                    block:
                        - - \[
                          - \]
                        - - $$
                          - $$
                    inline:
                        - - \(
                          - \)
        renderer:
            ## Set to true if you have HTML content inside Markdown
            unsafe: true
    tableOfContents:
        endLevel: 4
        ordered: true
        startLevel: 2
    highlight:
        noClasses: false
        codeFences: true
        guessSyntax: true
        lineNoStart: 1
        lineNos: true
        lineNumbersInTable: true
        tabWidth: 4

博客主题由极简的 M10c 迁移到结构复杂的 Stack

第一步 备份

第二步 切换到主分支准备“动刀”

第三步：清理旧主题并添加新主题

第四步：复制示例配置文件

1. 在你的项目根目录找到 themes/hugo-theme-stack/exampleSite。

2. 将其中的 hugo.yaml (或 config.yaml) 拷贝到你的根目录，并替换掉你原本的 hugo.toml。

3. 调整文件夹结构

4. 美好和定制

第一步备份

第二步切换到主分支准备“动刀”

1. 在你的项目根目录找到 `themes/hugo-theme-stack/exampleSite`。

2. 将其中的 `hugo.yaml` (或 `config.yaml`) 拷贝到你的根目录，并替换掉你原本的 `hugo.toml`。