神觉晓

@shenjuexiao

神觉晓

发表于

清除GitHub提交记录

Clear GitHub Commit History

📝 笔记总结

主要是有时候我的强迫症犯了：清除 GitHub 提交记录，核心是重写历史并强制推送。

📖 内容来源

清除 GitHub 提交记录，核心是重写历史并强制推送。操作前请务必备份，并注意：如果曾有人 Fork 或克隆过仓库，旧数据仍可能存在于他人本地或 GitHub 缓存中，无法从网络上彻底抹去。

方案一：清空所有历史，保留最新快照

如果你想让仓库看起来像全新的，只保留当前的文件状态，这是最简单的方法。

  1. 备份：将本地代码库复制到安全位置。
  2. 创建孤立分支：在项目目录下执行，这会创建一个没有父提交的全新分支。
    1
    git checkout --orphan new_branch
  3. 提交所有文件：把当前工作目录的所有文件加入并提交为一个新初始提交。
    1
    2
    git add -A
    git commit -m \"Initial commit (clean snapshot)\"
  4. 替换旧分支：删除原来的主分支（如 main 或 master），并把当前分支重命名为它。
    1
    2
    git branch -D main
    git branch -m main
  5. 强制推送：覆盖远程仓库的历史。
    1
    git push origin --force main

方案二：彻底删除 .git 目录后重新初始化

这个方法更直接，但会丢失所有分支配置和标签，适用于只想保留文件快照的场景。

  1. 删除 Git 仓库数据：进入项目目录，删除隐藏的 .git 文件夹。
    1
    rm -rf .git
  2. 重新初始化并提交：
    1
    2
    3
    4
    git init
    git add .
    git commit -m \"Initial commit\"
    git remote add origin <你的仓库地址>
  3. 强制推送：
    1
    git push --force --set-upstream origin main

方案三：删除特定文件或敏感提交

如果只是想删掉历史记录里的某个敏感文件（如密码、密钥），可以使用 git filter-repo 工具，它比旧版的 filter-branch 更快更安全。

  1. 安装：pip install git-filter-repo
  2. 删除文件：这会将指定文件从所有历史提交中移除。
    1
    git filter-repo --path 敏感文件名 --invert-paths
  3. 强制推送：git push origin --force --all（若涉及标签，也需推送 --tags）。

⚠️ 关键警告与善后

  • 秘密必须轮换：如果提交的是密码或密钥，立刻作废并重新生成。清除历史无法阻止别人在清除前已经拷贝，你必须默认它已经泄露。
  • 通知协作者：强制推送后，其他人的本地历史会与远程冲突。应通知他们重新克隆，而不是使用 git pull（合并）来更新，否则可能把旧历史又推回来。

发表于

Test

发表于

Test

发表于

Pelican 部署 GitHub 未生成文章

Pelican Has No Content

📝 笔记总结

  1. with: 部分添加 requirements 参数；
  2. 项目根目录创建 requirements.txt。

📖 内容来源

⚠️ 错误提示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# .github/workflows/pelican.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [\"main\"]
  workflow_dispatch:
jobs:
  deploy:
    uses: \"getpelican/pelican/.github/workflows/github_pages.yml@main\"
    permissions:
      contents: \"read\"
      pages: \"write\"
      id-token: \"write\"
    with:
      settings: \"publishconf.py\"

使用官方的 pelican.yml，content 文件夹内有测试的文章 *.md，但是没有生成文章页面。

Pelican Build Pelican Site

💡 错误原因

Could not import ‘markdown.Markdown’. Have you installed the ‘markdown’ package?
GitHub Actions 环境中没有安装 Markdown 支持，所以 Pelican 无法解析 .md 文件，导致处理了 0 篇文章。

✅ 解决方法

with: 部分添加 requirements 参数

  • 指定需要安装的 Python 模块：
1
2
3
with:
  settings: \"publishconf.py\"
  requirements: \"pelican[markdown] typogrify markdown-include\"
  • 或者指定一个requirements文件： -r requirements.txt：
1
2
3
with:
  settings: \"publishconf.py\"
  requirements: \"-r requirements.txt\"
  • 完整的工作流文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
name: Deploy to GitHub Pages

on:
  push:
    branches: [\"main\"]
  workflow_dispatch:

jobs:
  deploy:
    uses: \"getpelican/pelican/.github/workflows/github_pages.yml@main\"
    permissions:
      contents: \"read\"
      pages: \"write\"
      id-token: \"write\"
    with:
      settings: \"publishconf.py\"
      requirements: \"-r requirements.txt\"

项目根目录创建 requirements.txt：

1
2
# 导出当前环境所有包
pip freeze > requirements.txt

典型的 Pelican 项目 requirements.txt 参考：

1
2
3
4
5
6
7
8
9
10
# Pelican 核心 + Markdown 支持
pelican[markdown]==4.12.0
# 排版优化（智能引号、连字符等）
typogrify==2.1.0
# 支持在 Markdown 中包含其他文件               
markdown-include==0.8.1
# 代码高亮
pygments==2.17.2
# 同时支持 Markdown 和 reStructuredText
# pelican[markdown,html_rst]

发表于

SvelteKit 构建 GitHub Pages

GitHub Actions Free Minutes

📝 笔记总结

  1. 增加文件：svelte.config.js ；
  2. 增加文件：src/routes/+layout.js 。

📖 内容来源

💡错误提示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: 'main'

jobs:
  build_site:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      # If you're using pnpm, add this step then change the commands and cache key below to use `pnpm`
      # - name: Install pnpm
      #   uses: pnpm/action-setup@v6
      #   with:
      #     version: 8

      - name: Install Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm i

      - name: build
        env:
          BASE_PATH: '/${{ github.event.repository.name }}'
        run: |
          npm run build

      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v5
        with:
          # this should match the `pages` option in your adapter-static options
          path: 'build/'

  deploy:
    needs: build_site
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

使用官方的 deploy.yml ，运行失败，下面提示：

SvelteKit GitHub Pages Upload Artifacts

错误表明 GitHub Actions 在运行 actions/upload-pages-artifact@v5 时，找不到 build/ 目录。

本地构建文件都生成在 .svelte-kit/output/server/ 目录下，而不是 build 文件夹，说明 adapter-static 可能没有正确执行，或者构建过程在预渲染阶段失败了。

🚀 官方方法

使用 npm i -D @sveltejs/adapter-static 安装，然后将适配器添加到你的 svelte.config.js 中。

  1. 增加文件：svelte.config.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import adapter from '@sveltejs/adapter-static';

export default {
	kit: {
		adapter: adapter({
			// default options are shown. On some platforms
			// these options are set automatically — see below
			pages: 'build',
			assets: 'build',
			fallback: undefined,
			precompress: false,
			strict: true
		})
	}
};
  1. 增加文件：src/routes/+layout.js
1
2
// This can be false if you're using a fallback (i.e. SPA mode)
export const prerender = true;

💎 解决结果

文件生成在 .svelte-kit/output/server/ 和 build 文件夹。

SvelteKit npm run build

发表于

GitHub Actions 免费额度

GitHub Actions Free Minutes

📝 笔记总结

今天发现私有仓库的 Actions 运行失败了，下面提示：

The job was not started because recent account payments have failed or your spending limit needs to be increased. Please check the ‘Billing & plans’ section in your settings

我查询了一下，原来是免费额度用完了，顺便多了解了下。

GitHub Actions Free Minutes Annotations

查询：Settings → Billing and plans → Overview

页面中有一个 "Usage by products" 区域，点击 Actions 标签。

额度不够，是不是设置一个小号或者组织差不多够用。

📖 内容来源

GitHub Actions 的免费额度主要根据仓库是公开还是私有以及账户订阅计划来决定。核心原则是：公开仓库完全免费，私有仓库有每月额度限制。

把不同计划的免费额度表格查看：

账户计划 免费分钟数/月 (私有仓库) 免费存储空间 (工件与缓存)
GitHub Free (个人) 2,000 分钟 500 MB
GitHub Free (组织) 2,000 分钟 500 MB
GitHub Pro 3,000 分钟 1 GB
GitHub Team 3,000 分钟 2 GB
GitHub Enterprise Cloud 50,000 分钟 50 GB

提示：表格中的存储额度是工件（Artifacts） 和缓存（Cache） 共享的总和。缓存每个仓库还有额外的 10 GB 限制。

💡 超限后会发生什么？

  • 如果设置了支出限额：一旦用完免费额度，超出的部分会按标准费率（Linux 约 $0.008/分钟）计费，直到设置的限额为止。
  • 如果未设置支出限额（限额为 0）：私有仓库的 Actions 会停止运行，直到下一个计费周期重置。

🚀 一些关键细节和限制

  • 工作流并发限制：GitHub Free 计划最多允许 20 个作业并发运行。如果超出，作业会进入排队状态。
  • 单次作业超时：GitHub 托管运行器上的单个作业最多运行 6 小时，超时后会被自动取消。
  • 存储扣费逻辑：存储费用是按小时计费并累积的。删除文件只能阻止未来继续计费，但无法免除文件在留存期间已经产生的费用。
  • 账户计费独立：个人账户和组织的付费额度是分开的，为组织付款不会覆盖到个人账户。
  • Copilot 代码评审：这项功能（如果启用）在私有仓库中也会消耗 Actions 分钟数。

💎 总结与建议

如果是开源项目或个人学习，公开仓库是零成本的最佳选择。如果必须使用私有仓库，建议密切关注仪表盘上的用量，并根据实际情况设置支出限额，防止意外超支。

发表于

Next.js 博客模板

Next.js Blog Template

📝 笔记总结

目前最好用的 Next.js 博客模板，首选功能最全的 tailwind-nextjs-starter-blog，它几乎涵盖了个人博客可能需要的所有功能，而且社区非常活跃。如果想找一个更轻量、更现代的选择，nextjs-mdx-blog-template 也很不错，基于最新的 Next.js 15 和 React 19

Next-js-Blog-Boilerplate

项目名称： ixartz/Next-js-Blog-Boilerplate
适用场景： 快速上手，希望项目结构清晰、易于维护的开发者。
核心特点：

  • 简洁的 CLI 工具一键创建项目，快速启动开发。
  • 整合了 Radix UI、Lucide 图标等现代 UI 库，界面组件丰富。
  • 项目结构清晰规范，易于维护和二次开发。
  • 内置 TypeScript 支持和 ESLint 配置，保证代码质量。
    项目演示： creativedesignsguru.com
    GitHub 地址： github.com/ixartz/Next-js-Blog-Boilerplate

next-mdx-blog

项目名称： leerob/next-mdx-blog
适用场景： Next.js 初学者，或希望从一个轻量、官方风格项目开始进行学习的开发者。
核心特点：

  • 由 Vercel 的开发者关系负责人（Lee Robinson）维护，代码结构清晰规范。
  • 基于 Next.js、MDX 和 Tailwind CSS 构建，轻量简洁。
  • 可作为理解 Next.js + MDX 博客核心逻辑的绝佳起点，便于进行高度定制。
  • 集成了 Vercel Analytics。
    项目演示： next-blog-mdx.vercel.app
    GitHub 地址： github.com/leerob/next-mdx-blog

🌟 nextjs-mdx-blog-template

项目名称： loke-dev/nextjs-mdx-blog-template
适用场景： 追求极致简洁、最新 Web API 和流畅动画体验的开发者。
核心特点：

nextjs-portfolio-blog-research

项目名称： zhengzangw/nextjs-portfolio-blog-research
适用场景： 追求现代化设计、国际化支持，以及希望尝试最新技术栈的研究者、开发者与创作者。
核心特点：

nextjs-sanity-blog

项目名称： @multidots/sanity-blog-theme
适用场景： 需要复杂内容结构（如有独立作者、分类、SEO管理）的团队或个人项目。
核心特点：

🌟 NotionNext

项目名称： QiLOL/NotionNext
适用场景： 习惯使用 Notion 写作，希望将 Notion 作为 CMS（内容管理系统）快速搭建博客或知识库的用户。
核心特点：

  • 基于 Next.js 和 Notion API，将 Notion 笔记渲染为静态博客页面。
  • 内置多达 25 种主题，可一键切换。
  • 支持多种评论系统（Twikoo, Giscus, Gitalk 等）。
  • 项目活跃，持续更新，提供详细的中文文档。
    项目演示： preview.tangly1024.com
    GitHub 地址： github.com/QiLOL/NotionNext

starter-nextjs-blog

项目名称： Hashnode/starter-nextjs-blog
适用场景： 习惯在云端写稿、管理内容，又想自己搭建前端、保持UI高度自定义的创作者。
核心特点：

tailblaze

项目名称： tailblaze
适用场景： 目标是将博客部署到 Cloudflare Pages，或需要一个高性能静态站点的开发者。
核心特点：

  • 功能齐全，PWA 就绪，支持离线访问能力。
  • 强调性能和页面速度，经过 Lighthouse 优化。
  • 支持静态导出 (SSG)，可无缝部署到 Cloudflare Pages、Netlify 等平台。
  • 基于 Next.js、Tailwind CSS 和 TypeScript 构建。
    项目演示： tailblaze.pages.dev
    GitHub 地址： github.com/samrobbins/tailblaze

🌟 tailwind-nextjs-starter-blog

项目名称： timlrx/tailwind-nextjs-starter-blog
适用场景： 个人技术博客、作品集网站，以及希望从 Jekyll/Hugo 迁移到 Next.js 的用户。
核心特点：

  • 功能非常全面，社区活跃（9.7k Star），可视为"功能最全的博客启动模板"。
  • 基于 Next.js、TypeScript 和 Tailwind CSS 构建，使用 Contentlayer 管理内容逻辑。
  • 集成多种分析、评论、邮件订阅方案（如 Pliny 插件），支持 SEO、RSS、数学公式（KaTeX）、搜索（Kbar/Algolia）等。
  • 提供多种博客布局和列表布局，支持多作者和标签系统。
    项目演示： tailwind-nextjs-starter-blog.vercel.app
    项目演示： 项目 README 列出多个使用该模板的示例网站。
    GitHub 地址： github.com/timlrx/tailwind-nextjs-starter-blog

发表于 更新于

知识库与博客结合的模板

Wiki and Blog SCG Template

知识库与博客的结合，关键在于处理好结构化知识沉淀与碎片化内容输出之间的关系。以下整理了三种主流的模板方案，可以根据自己对技术栈的偏好和功能需求来选择。

1️⃣ 文档驱动型：VitePress + 博客主题

适合：偏好纯文档风格，希望将技术笔记和博客文章统一管理，且追求极致性能的技术写作者。

这个方案基于 VitePress（Vue 驱动的静态站点生成器），通过 vitepress-theme-teek 这类主题，在原生文档站基础上注入博客功能。模板会按文件路径自动生成侧边栏，构建出结构化的知识库；博客功能则作为“碎片化知识”的补充，支持文章分类、标签和归档。

  • 技术栈：VitePress、Vue、Markdown。
  • 核心能力：自动生成侧边栏/目录页、全文搜索、暗黑模式、支持评论系统（Giscus/Twikoo）。
  • 快速体验：可直接克隆 chuiyu_Wiki 这类现成项目，或参照 Teek 主题文档初始化。

vitepress-theme-teek

chuiyu_Wiki

2️⃣ 博客优先型：Astro 主题（知识图谱 + 搜索）

适合：内容较为丰富、需要强大检索能力来盘活知识库的博主。

Astro 因为对内容站点的高性能支持，出现了一批优秀的“博客+知识库”主题。例如 astro-theme-iris，它实现了双链笔记（Wikilink）和知识图谱（Graph View），能直观看到文章间的关联。配合 FlexSearch 实现的实时全文检索，能极大提升查找历史笔记的效率。而 qiyuan-blog-template 则更进一步，在 Astro 基础上集成了 RAG（检索增强生成）AI 问答，让读者可以直接向你的知识库提问。

  • 技术栈：Astro、TypeScript、FlexSearch/D3.js。
  • 核心能力：双链预览、知识图谱可视化、高性能搜索、AI 问答（RAG）。
  • 快速体验：在 GitHub 搜索对应仓库，点击 "Use this template" 即可一键创建。

astro-theme-iris

qiyuan-blog-template

3️⃣ 全栈管理型：Next.js 全功能平台

适合：需要后台管理、富文本编辑，且希望拥有 AI 辅助写作能力的深度内容创作者。

如果觉得静态模板定制性有限，可以考虑 Next.js 打造的全栈平台。例如 Petrichor，它不仅是一个展示站点，更包含完整的 CMS（内容管理系统），支持富文本编辑、知识库目录树，甚至集成了 AI 续写、改写和周报生成功能。next-ai-blog-cms 则侧重技术实现，提供了完整的后台管理界面和基于向量检索（RAG）的站内问答，实现了从写作、存储到智能问答的闭环。

  • 技术栈：Next.js、Supabase/PostgreSQL、Prisma、TailwindCSS。
  • 核心能力：AI 写作助手、富文本编辑器、后台仪表盘、RAG 知识库问答。
  • 快速体验：项目通常支持一键部署到 Vercel，需准备好数据库（如 Supabase）和环境变量。

next-ai-blog-cms

📊 表格对比

模板方案 推荐场景 主要技术 核心特色
VitePress + Teek 主题 文档技术博客、笔记整理 VitePress, Vue 文档/博客双模式，自动生成结构化目录
Astro 主题 (Iris/Qiyuan) 知识图谱展示、AI 问答博客 Astro, D3.js, RAG 可视化知识图谱，站内 AI 助手（RAG）
Next.js 全栈平台 (Petrichor) 需后台管理、AI 辅助创作 Next.js, Supabase, Prisma 富文本编辑器，AI 写作与周报，后台 CMS

🌟 选型建议

  1. 如果追求简单和速度：方案一（VitePress）最轻量，维护成本低，适合以 Markdown 为主的笔记博主。
  2. 如果希望内容被“盘活”：方案二（Astro）的图谱和 AI 能力，能让你的旧文章通过关联和问答重新被发现。
  3. 如果需要深度管理内容：方案三（Next.js）提供了完整的后台和 AI 写作流，更适合系列化、长周期的内容创作。

以上方案均为开源项目，除自行部署外，也可参考 WorkBuddy + MaxKB 等方案，为现有静态博客快速接入知识库问答能力。

0%