Test

Pelican 部署 GitHub 未生成文章

📝 笔记总结

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

📖 内容来源

• Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
• 使用自定义GitHub Actions工作流将站点发布GitHub Pages中

⚠️ 错误提示

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，但是没有生成文章页面。

💡 错误原因

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

📝 笔记总结

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

📖 内容来源

• SvelteKit 构建和部署 - 静态网站生成 - GitHub Pages
• SvelteKit Build and deploy - Static Site Generation - GitHub Pages

💡错误提示

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 ，运行失败，下面提示：

错误表明 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
		})
	}
};

2. 增加文件：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 文件夹。

GitHub Actions 免费额度

📝 笔记总结

今天发现私有仓库的 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

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

查询：Settings → Billing and plans → Overview

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

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

📖 内容来源

• GitHub Actions 免费额度（DeepSeek）

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

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

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

💡 超限后会发生什么？

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

🚀 一些关键细节和限制

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

💎 总结与建议

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

Next.js 博客模板

📝 笔记总结

目前最好用的 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 和流畅动画体验的开发者。
核心特点：

• 采用 Next.js 15 的 App Router 和 React 19 Server Components。
• 内置 View Transitions API，实现平滑的页面过渡动画。
• 使用 shadcn/ui（Radix UI）保证可访问性，Shiki 实现代码高亮。
• 项目结构清晰，对 SEO 友好，开箱即用。
  项目演示： nextjs-mdx-blog-template.vercel.app
  备用演示： nextjs-mdx-blog.loke.dev
  GitHub 地址： github.com/loke-dev/nextjs-mdx-blog-template

nextjs-portfolio-blog-research

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

• 技术栈新，采用 Next.js 15、React 19 和 Tailwind CSS 4。
• UI 精美，使用 shadcn/ui 和 Framer Motion 构建组件与动画。
• 支持 AI 辅助定制（Cursor Rules）和中英双语国际化（i18n）。
• 内置丰富的作品集、博客模块，SEO 优化完善（JSON-LD、Open Graph），性能出色。
  项目演示： nextjs-portfolio-blog-research.vercel.app
  备用演示： www.zangwei.dev/open-source/nextjs-portfolio-blog-research/docs
  GitHub 地址： github.com/zhengzangw/nextjs-portfolio-blog-research

nextjs-sanity-blog

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

• 结合 Sanity CMS（强大的结构化内容平台），提供灵活的内容建模能力。
• 包含页面构建器和编辑器友好界面，方便非技术人员管理内容。
• 支持多作者、分类、标签、SEO 元数据管理等复杂内容结构。
• 基于 Next.js 和 Sanity 官方最佳实践构建。
  项目演示： www.sanity.io/templates/nextjs-blog
  GitHub 地址： github.com/multidots/nextjs-sanity-blog
  GitHub 备用： github.com/multidots/sanity-blog

🌟 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高度自定义的创作者。
核心特点：

• 结合 Hashnode 强大的云端 CMS 管理后台，前端完全自定义。
• 通过 GraphQL API 获取内容，支持实时预览。
• 内置 SEO 优化，与 Hashnode 生态无缝集成。
• 适合已有 Hashnode 账号、希望保持写作习惯但拥有独立前端的用户。
  项目演示： github.com/Hashnode/starter-nextjs-blog
  GitHub 地址： github.com/Hashnode/starter-nextjs-blog

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

知识库与博客结合的模板

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

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

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

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

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

vitepress-theme-teek

• 项目演示：VitePress Teek 主题演示站
• GitHub 地址：Kele-Bingtang/vitepress-theme-teek

chuiyu_Wiki

• 项目演示：chuiyu.wiki
• GitHub 地址：ana52070/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

• 项目演示：LemonAdorable 的 Astro Iris 主题演示
• GitHub 地址：LemonAdorable/astro-theme-iris

qiyuan-blog-template

• 项目演示：qiyuan.icu
• GitHub 地址：violet27chen/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

• 项目演示：fcppddl.top
• GitHub 地址：fcppddl/next-ai-blog-cms

📊 表格对比

🌟 选型建议

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

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

npm 切换国内镜像

📝 笔记总结

推荐使用 nrm，命令简单，切换方便。

1
2
3
4
5
6
7
8
9
10
11

# 1. 全局安装 nrm
npm install -g nrm

# 2. 查看所有可用的源（带 * 的是当前源）
nrm ls

# 3. 切换到淘宝镜像
nrm use taobao

# 4. 验证是否设置成功
npm config get registry

📖 内容来源

• NPM切换国内镜像（DeepSeek）

🎯 最新稳定镜像地址

在国内使用 npm，切换镜像源几乎是必做的优化。核心操作很简单，但注意务必使用最新的地址。

淘宝 NPM 镜像（强烈推荐）：

1

https://registry.npmmirror.com/

特别提醒：淘宝 NPM 官方源地址已于 2024 年迁移至 npmmirror.com，旧的 npm.taobao.org 域名已废弃，请勿继续使用。

其他备选国内镜像源还有：

• 腾讯云：https://mirrors.cloud.tencent.com/npm/
• 华为云：https://mirrors.huaweicloud.com/repository/npm/
• 阿里云：https://npm.aliyun.com

🔧 切换方法

临时使用（仅对当前命令生效）

安装单个包时，直接通过 --registry 参数指定：

1

npm install [package-name] --registry=https://registry.npmmirror.com

这种方法快速、安全，适合临时下载某个包。

永久修改（全局生效）

通过 npm config set 命令修改全局配置，这是最常用的方法：

1
2
3
4
5

# 设置淘宝镜像为默认源
npm config set registry https://registry.npmmirror.com

# 验证是否设置成功
npm config get registry

执行后，所有 npm install 都将使用国内镜像。

高级管理：nrm

如果经常需要在多个镜像源（如官方、淘宝、公司私有源）间切换，推荐使用 nrm 工具来管理：

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 全局安装 nrm
npm install -g nrm

# 2. 查看所有可用的源（带 * 的是当前源）
nrm ls

# 3. 切换到淘宝镜像
nrm use taobao

# 4. 验证是否设置成功
npm config get registry

这样，只需要输入 nrm use taobao 或 nrm use npm 就能一键切换，无需记忆或输入长串地址。

可以随时切换回来，或者换成其他。

💡 备选方案：cnpm

除了修改 npm 源，也可以直接安装 cnpm 工具，自动使用淘宝镜像，与 npm 命令基本一致：

1
2

npm install -g cnpm --registry=https://registry.npmmirror.com
# 之后使用 cnpm 代替 npm，如：cnpm install

按需选择最适合的方法就好。设置完后可以运行 npm config get registry 确认一下，新地址是 https://registry.npmmirror.com/ 就说明成功了。

Eleventy 模板

项目名称： 11ty-Indie-Web-Blog-Starter
适用场景： 独立网络 / 创作者博客
核心特点： 为参与"独立网络"的创作者设计，支持暗色模式、客户端搜索（FlexSearch）、Webmention、微格式等，并对可访问性做了优化。
项目演示： indieweb-blog-starter.netlify.app
GitHub 地址： github.com/brennanbrown/11ty-Indie-Web-Blog-Starter

11ty-subspace-builder

项目名称： 11ty-subspace-builder
适用场景： 高性能博客
核心特点： "曲速"启动的博客模板，基于 Tachyons 工具类 CSS，特色是构建时生成 Open Graph 图片，并提供了 Docker 支持。
项目演示： subspace-builder.nicholas.clooney.io
GitHub 地址： github.com/TheClooneyCollection/11ty-subspace-builder

11ty-template

项目名称： 11ty-template
适用场景： 可自定义的启动模板
核心特点： 整合了 Nunjucks、TailwindCSS 和 SASS，并包含了导航、站点地图和文件压缩等插件。
项目演示： flowbite.com
GitHub 地址： github.com/AlexKeyCodes/11ty-template

🌟 eleventy-base-blog

项目名称： eleventy-base-blog
适用场景： 博客新手 & 通用起点
核心特点： Eleventy 官方团队维护的博客启动器，文档齐全，会随 Eleventy 版本更新。包含 RSS、站点地图、标签和图片优化，开箱即用地实现完美的 Lighthouse 性能评分。
项目演示： eleventy-base-blog.netlify.app
GitHub 地址： github.com/11ty/eleventy-base-blog

🌟 Eleventy Excellent

项目名称： Eleventy Excellent
适用场景： 功能丰富的博客
核心特点： 功能全面的博客/通用型模板，开箱即用。集成了自动深色/浅色模式、YouTube 轻量级嵌入、自动生成的 Open Graph 图片和分页归档等特性，非常"省心"。
项目演示： eleventy-excellent.netlify.app
GitHub 地址： github.com/11ty/eleventy-excellent
GitHub 备用： github.com/madrilene/eleventy-excellent

eleventy-garden

项目名称： eleventy-garden
适用场景： 数字花园 / 笔记
核心特点： 支持双向链接和反向链接，适合构建一个互联的知识网络或公开笔记。
项目演示： eleventy-garden.netlify.app
GitHub 地址： github.com/11ty/eleventy-garden
GitHub 备用： github.com/binyamin/eleventy-garden

🌟 Eleventy High Performance Blog

项目名称： Eleventy High Performance Blog
适用场景： 性能极限追求
核心特点： 由谷歌工程师构建，可达到完美的 Lighthouse 分数（目前已归档，但仍是优秀参考）。
项目演示： www.industrialempathy.com/posts/eleventy-high-performance-blog/
GitHub 地址： github.com/google/eleventy-high-performance-blog

Eleventy Netlify Boilerplate

项目名称： Eleventy Netlify Boilerplate
适用场景： CMS 支持 / 客户项目
核心特点： 在 Netlify 上部署的经典方案，集成了 Decap CMS（原 Netlify CMS），让非技术人员也能通过友好的界面管理内容。
项目演示： eleventy-netlify-boilerplate.netlify.app
GitHub 地址： github.com/danurbanowicz/eleventy-netlify-boilerplate

eleventy-simple

项目名称： eleventy-simple
适用场景： 极简博客
核心特点： 基于官方 Base Blog 构建，并结合了 Simple.css 框架，让你无需编写复杂 CSS 就能获得一个干净、好看的博客外观。
项目演示： eleventy-simple.pages.dev
GitHub 地址： github.com/lkhrs/eleventy-simple

Halide

项目名称： Halide
适用场景： 摄影 / 作品集
核心特点： 响应式图像作品集网站模板，与 Tina CMS 深度集成，非常适合摄影师、设计师等需要展示视觉作品的用户。
项目演示： halide.netlify.app
GitHub 地址： github.com/danurbanowicz/halide

Living Coral

项目名称： Living Coral
适用场景： 中文博客
核心特点： 优雅的中文静态博客模板，基于 Eleventy 和 Tailwind CSS 构建，品牌色为"活珊瑚橘"。内置文章目录（TOC）、深浅色主题、Giscus 评论、音乐播放器（APlayer）等丰富特性。
项目演示： living-coral.vercel.app
备用演示： www.antares.xin
GitHub 地址： github.com/Aesculapius11/Living-Coral

Niepce

项目名称： Niepce
适用场景： 摄影 / 作品集
核心特点： 专为摄影师和艺术家设计，支持多种图片网格布局（瀑布流、等宽等）和 EXIF 信息展示。
项目演示： niepce.netlify.app
备用演示： www.antares.xin
GitHub 地址： github.com/GoOz/Niepce

Retro Garden

项目名称： Retro Garden
适用场景： 个性 / 创意站点
核心特点： 融合了 WebC 组件、IndieWeb 理念和复古风格，同时保持现代工具链，风格独特。
项目演示： retro-garden-eleventy-theme.netlify.app
GitHub 地址： github.com/kylereddoch/retro-garden-eleventy-theme

Retroweird

项目名称： Retroweird
适用场景： 个性 / 复古风格博客
核心特点： 受 GeoCities、MySpace 等 Web 1.0 美学启发，内置了 6 种不同的复古主题，让你轻松回到互联网的"蛮荒时代"，风格独特。
项目演示： retroweird.netlify.app
GitHub 地址： github.com/brennanbrown/retroweird

Subtle

项目名称： Subtle
适用场景： 极简 / 内容优先网站
核心特点： 一个极简的 Eleventy v4 微启动器，专为内容优先的网站设计，非常轻量。
项目演示： subtle-eleventy-starter.netlify.app
GitHub 地址： github.com/11ty/eleventy-starter-subtle

Eleventy 快速安装

Eleventy

技术栈：Node.js
官方网站：11ty.dev
项目地址：github.com/11ty/eleventy
模板演示：eleventy-simple.pages.dev
插件演示： fastcomments.com/commenting-system-for-11ty

📝 笔记总结

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 检查 Node.js 版本
node --version
# 创建项目目录
mkdir eleventy-sample
# 进入项目目录
cd eleventy-sample
# 创建 package.json，-y 使用默认值跳过问卷
npm init -y
# 如果项目中使用 ESM 而不是 CommonJS
npm pkg set type=\"module\"
# 安装 Eleventy 并保存到项目的 `package.json` 
npm install @11ty/eleventy
# 运行本地项目版本 Eleventy
npx @11ty/eleventy
# 创建两个新的模板文件
echo '<!doctype html><title>Page title</title><p>Hi</p>' | out-file -encoding utf8 'index.html'
echo '# Heading' | out-file -encoding utf8 'README.md'
# 创建好模板后，再次运行 Eleventy
npx @11ty/eleventy
# --serve 启动支持热重载的本地 Web 服务器
npx @11ty/eleventy --serve

📖 内容来源

• Eleventy Documentation - Guide - Get Started

🚀 快速安装

🔍 Node.js > 18

1
2

# 检查 Node.js 版本
node --version

📁 步骤 1：创建项目目录

step 1 make a project directory

1
2
3
4

# 创建项目目录
mkdir eleventy-sample
# 进入项目目录
cd eleventy-sample

📦 步骤 2：安装 Eleventy

Step 2 Install Eleventy

1
2
3
4
5
6

# 创建 package.json，-y 使用默认值跳过问卷
npm init -y
# 如果项目中使用 ESM 而不是 CommonJS
npm pkg set type=\"module\"
# 安装 Eleventy 并保存到项目的 `package.json` 
npm install @11ty/eleventy

▶️ 步骤 3：运行 Eleventy

Step 3 Run Eleventy

1
2

# 运行本地项目版本 Eleventy
npx @11ty/eleventy

运行 Eleventy 后，命令行输出：

1

[11ty] Wrote 0 files in 0.03 seconds (v3.1.6)

但是，Eleventy 没有处理任何文件，只有一个空文件夹，因为里面没有模板。

📝 步骤 4：创建模板

Step 4 Create some templates

模板是一种内容文件，可以使用 Markdown、HTML、Liquid、Nunjucks 等格式编写，Eleventy 在构建站点时会将其转换成一个（或多个）页面。

1
2
3

# 创建两个新的模板文件
echo '<!doctype html><title>Page title</title><p>Hi</p>' | out-file -encoding utf8 'index.html'
echo '# Heading' | out-file -encoding utf8 'README.md'

• 如果 out-file 命令在 Windows 终端窗口中不可用（PowerShell 特有的命令），改用跨平台方法。
• 或者使用任何文本编辑器创建模板文件。
• 确保保存到项目文件夹，文件扩展名正确。

1
2

# 创建好模板后，再次运行 Eleventy
npx @11ty/eleventy

命令行输出大致如下所示：

1
2
3

[11ty] Writing _site/README/index.html from ./README.md (liquid)
[11ty] Writing _site/index.html from ./index.html (liquid)
[11ty] Wrote 2 files in 0.04 seconds (v3.1.6)

现在已将当前目录中的两个内容模板编译到输出文件夹中（默认为 _site）。

如果进一步试验模板文件语法，编辑以下示例 README.md 文件，其中使用了 Front Matter、Liquid 和 Markdown 语法。

1
2
3
4

---
title: Heading
---
# {{ title }}

👀 步骤 5：预览模板

Step 5 Gaze upon your templates

1
2

# --serve 启动支持热重载的本地 Web 服务器
npx @11ty/eleventy --serve

命令行输出大致如下所示：

1
2
3
4
5

[11ty] Writing _site/index.html from ./index.html (liquid)
[11ty] Writing _site/README/index.html from ./README.md (liquid)
[11ty] Wrote 2 files in 0.04 seconds (v3.1.6)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

Web 浏览器中打开：
http://localhost:8080/
或
http://localhost:8080/README/
查看 Eleventy 站点！
修改再次保存模板文件时，Eleventy 将自动刷新浏览器使用新的更改。

🌐 步骤 6：上线（可选）

Step 6 Put it online (optional)

输出文件夹（_site）包含了网站所有的静态构建文件，可以将此文件夹上传到任何 Web 主机。

更多信息查看部署文档：Eleventy Documentation - Services - Deployment

📚 步骤 7：继续学习

Step 7 Continue learning

• **添加更多内容：**试试 JavaScript、WebC（用于组件）、Nunjucks 和 Liquid。
• **使用布局文件：**不必在每个模板上重复样板代码。
• **添加配置文件：**以解锁 Eleventy 的高级功能。
• 将 CSS、JavaScript 或 Web 字体添加到项目中。
• **添加自动图像优化：**也非常容易。
• 了解更多 Eleventy 的命令行选项。
• 在项目中接入第三方 API 的数据。

📖 教程和入门项目

Tutorials and Starter Projects

从零开始（了解其工作原理）或使用官方博客入门项目（更快地启动和运行）。

GitHub 令牌分类

📝 笔记总结

• 个人访问令牌（Personal Access Tokens，PATs）
  • 细粒度个人访问令牌（Fine-grained PAT）
  • 经典个人访问令牌（Classic PAT）
• 其他用于自动化或应用集成的令牌
  • GitHub Actions 内置令牌 GITHUB_TOKEN
  • GitHub App 安装令牌 Installation Token
  • OAuth App 访问令牌

📖 内容来源

• GitHub 令牌分类详解（Deepseek）
• GitHub Token 分类（Deepseek）

🌟 GitHub 令牌分类

GitHub 令牌主要分为两大类：个人访问令牌（Personal Access Tokens, PATs） 和其他用于自动化或应用集成的令牌。其中，个人访问令牌又分为更安全的细粒度令牌（Fine-grained PAT）和传统的经典个人访问令牌（Classic PAT）。

• 个人访问令牌（Personal Access Tokens，PATs）
  • 细粒度个人访问令牌（Fine-grained PAT）
  • 经典个人访问令牌（Classic PAT）
• 其他用于自动化或应用集成的令牌
  • GitHub Actions 内置令牌 GITHUB_TOKEN
  • GitHub App 安装令牌 Installation Token
  • OAuth App 访问令牌

汇总 GitHub 主要令牌类型及其核心区别：

🛡️ 核心选择建议

为什么“细粒度”比“经典”更安全？

GitHub 官方强烈推荐优先使用细粒度个人访问令牌，原因在于其安全模型有显著提升：

1. 权限更精细：经典令牌的权限是粗放型的（如repo范围），一旦拥有，就能访问用户有权访问的所有仓库。而细粒度令牌可以精确控制到特定仓库的单个操作（如读/写）。
2. 降低泄露风险：如果细粒度令牌泄露，攻击者能造成的破坏被限制在极小的范围内，大大缩小了“爆炸半径”。

⚠️ 仍需使用“经典”令牌？

由于功能迭代需要时间，在某些场景下，你仍然需要使用经典个人访问令牌：

• 需要向自己不是成员的公共仓库贡献代码。
• 需要访问企业级别的资源或API。
• 作为外部协作者访问组织的仓库。

🤖 自动化场景的最佳实践

针对自动化任务，应遵循以下选择顺序：

1. GitHub Actions 中优先使用 GITHUB_TOKEN：这是最安全、最便捷的方式，令牌由系统自动生成和管理，仅在当前工作流中有效。
2. 组织级自动化优先考虑 GitHub App：GitHub App 的安装令牌具有短生命周期（1小时），且权限与特定的应用安装绑定，非常适合CI/CD等系统，比使用绑定个人账号的PAT更安全、更可控。
3. 个人脚本首选细粒度PAT：只有在上述方案都无法满足需求时，才创建个人访问令牌，并务必选择细粒度类型。

🔑 快速识别令牌类型

可以通过令牌的前缀来快速识别其类型：

• ghp_：经典个人访问令牌
• github_pat_：细粒度个人访问令牌
• gho_：OAuth App 访问令牌
• ghu_：GitHub App 用户访问令牌
• ghs_：GitHub App 安装访问令牌
• ghr_：GitHub App 刷新令牌