A modern, lightweight blog built with Astro https://zz3656.github.io/Atom/ https://zz3656.github.io/Atom/blog/astro-blog-tutorial/ https://zz3656.github.io/Atom/blog/astro-blog-tutorial/ Sat, 19 Sep 2026 00:00:00 GMT 从 Astro 内容集合、构建流水线、GitHub Pages 自动部署三个角度，拆解 Atom 博客是怎么从 Markdown 文件变成可访问的静态网站。 tutorial Astro 架构 GitHub Pages 部署 .github.io/Atom/` 下，**不是根目录**。 这意味着： - ✅ HTML 中写 `/Atom/blog/foo/` → 实际访问 `dist/blog/foo/index.html` → 200 - ❌ 但 `public/js/app.js` 默认会复制到 `dist/js/app.js`，**不在子路径下** - ❌ HTML 引用 `/Atom/js/app.js` → 404 **解决方法**：在 `scripts/minify-app-js.mjs` 里**预先**把 `public/js/app.js` 复制到 `public/Atom/js/app.js`，Astro build 时会一并复制到 `dist/Atom/js/app.js`。这也是为什么 build 必须分成两步（先 minify，再 build）。 ## 六、进一步学习 - 📖 [Astro 官方文档](https://docs.astro.build) - 📖 [Content Collections 指南](https://docs.astro.build/en/guides/content-collections/) - 📖 [GitHub Pages 部署](https://docs.astro.build/en/guides/deploy/github/) - 📖 [Markdown 语法参考](https://commonmark.org/) - 🎨 [Atom 博客](https://zz3656.github.io/Atom) — 上面所有理念的实际应用]]> https://zz3656.github.io/Atom/blog/markdown-guide/ https://zz3656.github.io/Atom/blog/markdown-guide/ Fri, 18 Sep 2026 00:00:00 GMT 掌握 Markdown 的常用语法——标题、列表、代码块、表格、引用、链接、图片——让你的博客写作效率翻倍。 guide Markdown 写作 教程 文档 这是一段引用文字。 > 可以跨多行。 ``` > 这是一段引用文字。 > 可以跨多行。 ## 水平线 三个短横线或星号： ```markdown --- ``` --- ## Frontmatter 元数据 每篇文章顶部用 YAML 格式声明元数据： ```markdown --- title: 文章标题 description: 用于 SEO 与社交分享卡片 pubDate: 2026-09-20 updatedDate: 2026-09-21 # 可选：文章更新时间 heroImage: /medias/hero.jpg # 可选：文章顶部大图 featuredImage: /medias/og.jpg # 可选：OG 专用封面 category: 随笔 # 单数分类 tags: [标签1, 标签2] # 复数标签 reward: true # 可选：显示打赏码 draft: false # 草稿，构建时过滤 --- ``` ## 实战建议 1. **保持空行** —— 段落、标题、列表之间空一行，渲染更稳定 2. **代码块标注语言** —— 方便语法高亮，对屏幕阅读器也友好 3. **图片控制大小** —— Markdown 原生不支持，HTML `` 标签可控 4. **描述要短** —— Frontmatter 的 `description` 用于 SEO 摘要，建议 50-150 字 5. **合理分类** —— 分类是单数（一篇文章归一类），标签是复数（一篇文章可多个） 掌握这些语法，你就能高效地写出漂亮的博客文章了！ 🎉]]> https://zz3656.github.io/Atom/blog/welcome/ https://zz3656.github.io/Atom/blog/welcome/ Fri, 18 Sep 2026 00:00:00 GMT 拿到 Atom 模板后的最小可行动清单：站点信息、文章内容、Logo/Favicon、社交链接，以及每项该改哪些文件。 guide Atom 入门 客制化 💡 完成大约 10 分钟的修改就能让博客看起来是你的，而不是"Astro Demo"。 ## 一、站点基本信息（必改） **文件**：`src/consts.ts` 打开后只看一个文件，全站导航、Footer、SEO meta、RSS 名称都会跟着变： ```typescript export const SITE_TITLE = '你的博客名'; // 浏览器标签、SEO 标题、OG 标签、RSS 名称 export const SITE_NAME = 'MyBlog'; // 导航栏显示的短名称 export const SITE_DESCRIPTION = '你的博客描述'; // meta description、OG、Twitter Card export const AUTHOR = '你的名字'; // meta author 标签 export const SITE_LOGO = '/logos/logo.svg'; // 导航栏 Logo 路径 export const SITE_FAVICON = '/favicon.svg'; // 浏览器标签图标 // 首页 Hero 区域（图标 + 标题 + 描述 + 按钮）也可在同一个文件里客制化 export const SITE_HERO_ICON = ''; // 留空使用内置 Atom 原子 SVG；替换则放入 public/heroes/hero.svg export const HERO_TITLE = 'MyBlog'; // 首页大标题文本（支持 HTML 标签，如 ） export const HERO_DESCRIPTION = '你的博客一句话介绍'; export const HERO_ACTIONS = [ { label: '开始阅读 →', href: '/blog', variant: 'primary' }, { label: '关于此站', href: '/about', variant: 'secondary' }, ]; export const REPO_URL = 'https://github.com/你的用户名/你的仓库'; // ↑ Footer 的 "Atom" 链接指向这里（项目源代码仓库） export const SOCIAL_LINKS = { github: 'https://github.com/你的用户名', twitter: '', // 不填就不显示 email: '', // 不填就不显示 }; export const POSTS_PER_PAGE = 10; // 首页 / 文章列表每页显示几篇 ``` **字段说明**： | 字段 | 出现在哪里 | |---|---| | `SITE_TITLE` | 浏览器标题、SEO、OG、Twitter Card、RSS | | `SITE_NAME` | 导航栏 Logo 旁的短名 | | `SITE_DESCRIPTION` | meta description、社交分享卡片 | | `SITE_LOGO` / `SITE_FAVICON` | 导航栏 / 浏览器标签页 | | `SITE_HERO_ICON` / `HERO_TITLE` / `HERO_DESCRIPTION` / `HERO_ACTIONS` | 首页 Hero 区域（标题前的图标、大标题、CTA 按钮） | | `SOCIAL_LINKS.github` | Footer 的 🐙 GitHub（可改成项目仓库或个人主页）| | `REPO_URL` | Footer 的 "Atom" 链接，指向你的源代码仓库 | ## 二、替换示例文章（必改） **位置**：`src/content/blog/` 仓库默认附带 3 篇示例文章。建议至少删掉或替换成你自己的内容： ```bash # 删除示例文章 rm src/content/blog/welcome.md rm src/content/blog/astro-blog-tutorial.md # 保留 markdown-guide.md（学习 Markdown 语法用，删了也能从 GitHub 找到） # 或者用 CLI 交互式创建 npm run new ``` **创建第一篇文章的最小 Frontmatter**： ```markdown --- title: 我的第一篇文章 description: 简短描述（建议 50-150 字，用于 SEO 摘要和卡片预览） pubDate: 2026-09-20 category: 随笔 tags: [标签1, 标签2] draft: false # true 表示草稿，构建时被过滤掉 --- 正文内容... ``` 完整字段说明见 [Markdown 写作完全指南](/blog/markdown-guide/)。 ## 三、Logo、Favicon 和 Hero 图标（推荐改） 替换三个图片文件即可，**不需要改任何组件代码**： | 文件 | 用途 | 推荐尺寸 | |---|---|---| | `public/logos/logo.svg` | 导航栏左侧图标 | 32×32 矢量 | | `public/favicon.svg` | 浏览器标签页图标 | 任意，矢量自适应 | | `public/heroes/hero.svg` | 首页 Hero 大标题前的图标（可选） | 36×36 矢量 | 也可以是 PNG/WebP（对应 `SITE_*` 后缀改一下就行）。Hero 图标留空 `SITE_HERO_ICON = ''` 则用内置的 Atom 原子 SVG。 Hero 区域的**标题文案**、**描述段落**、**CTA 按钮**也都可以直接在 `src/consts.ts` 里的 `HERO_TITLE` / `HERO_DESCRIPTION` / `HERO_ACTIONS` 配置： ```typescript export const HERO_TITLE = 'MyBlog'; // 标题（可含 ） export const HERO_DESCRIPTION = '一个简洁、快速、优雅的现代博客。'; export const HERO_ACTIONS = [ { label: 'GitHub', href: 'https://github.com/yourname', variant: 'secondary' }, { label: '开始阅读 →', href: '/blog', variant: 'primary' }, ]; ``` 按钮可任意增删；`variant: 'primary' | 'secondary'` 控制样式，`hide: true` 跳过该按钮。 ## 四、关于页面（推荐改） **文件**：`src/pages/about.astro` 默认是个简单的占位页。改成你的自我介绍 + 站点说明，访客会更信任你的内容。 ## 五、部署到生产（最后一步） 代码改完后，提交并推送，CI 自动部署到 GitHub Pages： ```bash git add -A git commit -m "feat: 定制站点信息" git push origin main ``` GitHub Actions 会自动跑 `npm run build` 并部署。几分钟后访问你的 `https://<用户名>.github.io/<仓库名>/` 就能看到效果。 **首次部署配置**：进入 GitHub 仓库的 Settings → Pages → Source 选 **GitHub Actions**，并把 Workflow permissions 设为 **Read and write permissions**。 ## 完整清单速查 | 优先级 | 改什么 | 文件 | |---|---|---| | ⭐ 必改 | 站点信息 | `src/consts.ts` | | ⭐ 必改 | 示例文章 | `src/content/blog/*.md` | | ⭐ 推荐 | Logo + Favicon + Hero 图标 | `public/logos/logo.svg`, `public/favicon.svg`, `public/heroes/hero.svg`（可选）| | ⭐ 推荐 | 首页 Hero 文案与按钮 | `HERO_TITLE` / `HERO_DESCRIPTION` / `HERO_ACTIONS` 在 `src/consts.ts` | | 推荐 | 关于页面 | `src/pages/about.astro` | | 可选 | 主题 | `src/themes/` + 主题脚手架 `npm run theme:create ` | | 可选 | 社交链接 | `SOCIAL_LINKS` 在 `src/consts.ts` | ## 下一步 - 📚 [Markdown 写作完全指南](/blog/markdown-guide/)——所有可用语法 - 🏗️ [Atom 博客的技术架构解析](/blog/astro-blog-tutorial/)——想了解为什么这样设计 - 📖 [README](https://github.com/zz3656/Atom)——部署、CLI、主题开发文档]]>