【全】Obsidian + GitHub + Quartz 个人博客 简单 搭建教程

Obsidian GitHub Quartz 个人博客搭建教程完整详细版这篇文章会一步一步教你搭建一个免费的个人笔记博客。最终使用的方案是Obsidian GitHub Quartz GitHub Pages最终效果是你在 Obsidian 写笔记 ↓ Obsidian Git 插件自动上传 GitHub ↓ GitHub Actions 自动构建网站 ↓ GitHub Pages 自动发布 ↓ 别人通过网址访问你的博客适合这些场景1. 想把自己的学习笔记公开给别人看 2. 想长期更新 CTF、Linux、Docker、数据库、工具教程等文章 3. 想用 Markdown 写文章 4. 想插入图片、代码块和命令 5. 不想买服务器 6. 想用 GitHub 免费托管博客本教程以Windows 系统为主适合新手一步一步照着做。一、整体流程先看懂搭建过程可以分成 8 个阶段第一阶段安装基础环境 第二阶段下载并初始化 Quartz 第三阶段本地预览博客 第四阶段用 Obsidian 写文章 第五阶段上传到 GitHub 第六阶段配置 GitHub Pages 自动发布 第七阶段配置 Obsidian Git 自动同步 第八阶段优化网站外观、SEO、统计和图标不用一次全部理解照着步骤做就行。最终你的博客地址类似https://你的GitHub用户名.github.io/例如https://mooi-max.github.io/二、安装基础环境这一部分非常重要。后面所有命令都依赖这些环境。需要安装1. Git 2. Node.js 3. npm 4. Obsidian 5. GitHub 账号其中Git负责上传文件到 GitHub Node.js负责运行 Quartz npmNode.js 自带的包管理工具用来安装 Quartz 依赖 Obsidian负责写笔记 GitHub负责存放博客代码并发布网站2.1 安装 Git第一步打开 Git 官网浏览器打开https://git-scm.com/点击Download for Windows下载安装包。第二步安装 Git双击下载好的 Git 安装包。安装过程中如果你不懂每个选项是什么意思建议全部保持默认然后一直点Next Next Next Install Finish大部分新手不需要改安装选项。第三步检查 Git 是否安装成功安装完成后重新打开 CMD。打开方式Win R 输入 cmd 回车在 CMD 中输入git--version如果显示类似git version 2.xx.x说明 Git 安装成功。如果提示git 不是内部或外部命令可以尝试1. 关闭 CMD重新打开 2. 重启电脑 3. 重新安装 Git 4. 安装时确认勾选了添加到 PATH 的选项第四步配置 Git 用户名和邮箱Git 第一次使用建议设置用户名和邮箱。在 CMD 输入gitconfig--globaluser.name你的名字gitconfig--globaluser.email你的邮箱例如gitconfig--globaluser.namemooigitconfig--globaluser.email你的GitHub邮箱example.com查看是否配置成功gitconfig--globaluser.namegitconfig--globaluser.email如果能显示你刚才设置的内容说明配置成功。2.2 安装 Node.jsQuartz 需要 Node.js 才能运行。第一步打开 Node.js 官网浏览器打开https://nodejs.org/建议下载LTS 版本LTS 的意思是长期支持版比较稳定适合大多数人。第二步安装 Node.js双击下载好的安装包。安装过程中建议1. 一路 Next 2. 保持默认路径 3. 勾选 Add to PATH 或自动添加到环境变量 4. 点击 Install 5. 安装完成后点击 Finish如果你不懂选项保持默认即可。第三步检查 Node.js 是否安装成功重新打开 CMD输入node-v如果显示类似v22.x.x说明 Node.js 安装成功。如果显示node 不是内部或外部命令可以尝试1. 关闭 CMD 重新打开 2. 重启电脑 3. 重新安装 Node.js 4. 安装时确认添加到了 PATH2.3 检查 npmnpm 通常会随 Node.js 一起安装不需要单独下载安装。检查 npmnpm-v如果显示类似10.x.x或者11.x.x说明 npm 正常。如果node -v正常但npm -v不正常可以尝试1. 关闭 CMD 重新打开 2. 重启电脑 3. 重新安装 Node.js LTS2.4 安装 Obsidian浏览器打开https://obsidian.md/下载 Windows 版本并安装。安装完成后先不用急着创建仓库后面我们会用 Obsidian 打开 Quartz 项目文件夹。2.5 注册 GitHub 账号打开https://github.com/注册并登录。记住你的 GitHub 用户名后面仓库名要用到。例如你的 GitHub 主页是https://github.com/mooi-max那么你的 GitHub 用户名就是mooi-max2.6 最终检查打开 CMD依次输入git--versionnode-vnpm-v只要这三个都能显示版本号就可以继续。三、创建博客项目文件夹建议把博客放在一个固定目录例如C:\Users\你的用户名\Desktop\_study\blog打开 CMD执行cdC:\Users\你的用户名\Desktopmkdir_studycd_studymkdirblogcdblog如果你的桌面路径不同可以自己调整。你也可以直接用自己的路径比如D:\blog核心原则是路径不要太乱后面方便找到。四、下载 Quartz在刚才的blog文件夹中执行gitclone https://github.com/jackyzha0/quartz.git myblog执行成功后会出现一个新文件夹myblog进入这个文件夹cdmyblog4.1 如果 git clone 失败怎么办如果出现类似TLS connect error unexpected eof while reading一般是网络连接 GitHub 不稳定。可以先设置 Gitgitconfig--globalhttp.sslBackend schannelgitconfig--globalhttp.version HTTP/1.1然后重新克隆gitclone--depth1https://github.com/jackyzha0/quartz.git myblog如果之前已经生成了失败的myblog文件夹可以先删除rmdir/s /q myblog再重新执行 clone。五、安装 Quartz 依赖进入项目目录cdmyblog安装依赖npmi等待它执行完成。如果看到类似added xxx packages说明依赖安装成功。如果看到vulnerabilities先不用急着处理不影响博客搭建。不要一开始就乱执行npm audit fix否则可能导致依赖版本变化。六、初始化 Quartz执行npx quartz create它会出现选项。6.1 选择初始化方式如果出现Choose how to initialize the content选择Empty Quartz然后按回车。6.2 选择链接格式如果出现Choose how Quartz should resolve links in your content选择Treat links as shortest path这个适合 Obsidian 的双链写法例如[[Nmap常用命令]] [[Linux权限管理]]后面选项不懂就默认回车。七、本地启动博客在myblog文件夹中执行npx quartz build--serve如果成功会显示类似Started a Quartz server listening at http://localhost:8080打开浏览器访问http://localhost:8080如果能看到页面说明本地博客已经运行成功。停止服务的方法在 CMD 里按 Ctrl C八、用 Obsidian 打开项目打开 Obsidian选择打开本地文件夹作为仓库选择整个项目文件夹...\myblog不要只选择...\myblog\content原因后面要用 Obsidian Git 插件自动上传 Git 仓库在 myblog 根目录 如果只打开 content插件可能找不到 Git 仓库平时写文章的位置是myblog/content/九、让 Obsidian 左侧更清爽因为打开的是整个项目Obsidian 里可能会看到很多文件node_modules quartz package.json quartz.config.ts quartz.layout.ts可以隐藏不常用文件。进入 Obsidian设置 → 文件与链接 → 排除文件添加node_modules/ quartz/ public/ .github/ .git/ package.json package-lock.json quartz.config.ts quartz.layout.ts tsconfig.json这样 Obsidian 左侧主要显示content里的笔记。十、设置图片保存位置进入 Obsidian设置 → 文件与链接找到附件默认存放位置选择当前文件所在文件夹下的指定子文件夹子文件夹名称填assets以后你在文章里粘贴图片会自动放到当前文章目录下的assets文件夹中。例如content/CTF/assets/nmap-scan-01.png十一、设置新建笔记默认位置进入设置 → 文件与链接找到新建笔记的存放位置建议选择指定的文件夹文件夹填content这样新建笔记时默认就会放到content中不会跑到项目根目录。十二、创建博客目录结构在 Obsidian 的content文件夹中创建这些文件夹CTF Linux Docker 数据库 工具教程 随笔最后结构类似content/ ├── index.md ├── CTF/ ├── Linux/ ├── Docker/ ├── 数据库/ ├── 工具教程/ └── 随笔/注意在 Obsidian 新建笔记时文件名不要写.md。例如要创建index.md你只需要输入index不要输入index.md否则可能变成index.md.md十三、修改首页打开content/index.md写入--- title: 首页 description: 我的个人技术笔记记录 CTF、网络安全、Linux、Docker、数据库、工具教程和学习复盘。 --- # 我的个人技术笔记 这里是我的公开笔记博客主要记录 CTF、Linux、Docker、数据库、工具教程和学习过程。 ## 内容分类 - [[CTF/index|CTF 笔记]] - [[Linux/index|Linux 笔记]] - [[Docker/index|Docker]] - [[数据库/index|数据库]] - [[工具教程/index|工具教程]] - [[随笔/index|随笔]] ## 最近整理方向 - CTF 靶机复盘 - Web 安全基础 - Linux 常用命令 - Docker 部署记录 - 数据库学习笔记十四、创建分类首页例如在content/CTF/里面新建笔记index内容--- title: CTF 笔记 description: 记录 CTF、靶机和 Web 安全相关学习内容。 tags: - CTF --- # CTF 笔记 这里整理 CTF、靶机、Web 安全相关内容。 ## 信息收集 - [[Nmap常用命令]] ## Web 安全 后续可以整理 SQL 注入、文件上传、XSS 等内容。 ## 靶机复盘 后续可以记录靶机练习过程。十五、写第一篇文章在content/CTF/中新建Nmap常用命令内容--- title: Nmap常用命令 description: 记录 Nmap 在 CTF 和靶机测试中的常用扫描命令、参数说明和实战用法。 date: 2026-04-29 tags: - CTF - Nmap - 信息收集 --- # Nmap常用命令 Nmap 是常用的端口扫描和服务识别工具。 ## 常用扫描 bash nmap -sC -sV 192.168.56.105 ## UDP 扫描 bash nmap -sU 192.168.56.105 ## 相关笔记 - [[CTF/index|CTF 笔记]]写完后重新本地预览npx quartz build--serve打开http://localhost:8080检查首页、分类页、文章页是否能访问。十六、修改网站标题和配置打开quartz.config.ts找到pageTitle:Quartz 4,改成pageTitle:Mooi 的个人技术笔记,或者pageTitle:Mooi 的网络安全与技术笔记,找到baseUrl:如果你的 GitHub 仓库是你的用户名.github.io例如mooi-max.github.io那么写baseUrl:mooi-max.github.io,注意不要写 https:// 不要在最后加 /找到locale:建议设置locale:zh-CN,十七、创建 GitHub 仓库登录 GitHub点击New repository如果你想让博客地址是https://你的用户名.github.io/仓库名必须是你的用户名.github.io例如用户名是mooi-max仓库名就是mooi-max.github.io创建时建议Public 不要勾选 README 不要添加 .gitignore 不要添加 license十八、连接 GitHub 仓库回到 CMD进入项目目录cdC:\Users\你的用户名\Desktop\_study\blog\myblog查看远程仓库gitremote-v修改 origingitremote set-url origin https://github.com/你的用户名/你的用户名.github.io.git例如gitremote set-url origin https://github.com/mooi-max/mooi-max.github.io.git添加 Quartz 官方仓库作为上游gitremoteaddupstream https://github.com/jackyzha0/quartz.git如果提示upstream already exists不用管。十九、创建 GitHub Actions 部署文件在项目根目录创建.github/workflows/deploy.yml如果没有.github文件夹就手动创建.github └── workflows └── deploy.ymldeploy.yml内容name:Deploy Quartz site to GitHub Pageson:push:branches:-v4permissions:contents:readpages:writeid-token:writeconcurrency:group:pagescancel-in-progress:falsejobs:build:runs-on:ubuntu-22.04steps:-uses:actions/checkoutv4with:fetch-depth:0-uses:actions/setup-nodev4with:node-version:22-name:Install Dependenciesrun:npm ci-name:Build Quartzrun:npx quartz build-name:Upload artifactuses:actions/upload-pages-artifactv3with:path:publicdeploy:needs:buildenvironment:name:github-pagesurl:${{steps.deployment.outputs.page_url}}runs-on:ubuntu-lateststeps:-name:Deploy to GitHub Pagesid:deploymentuses:actions/deploy-pagesv4二十、提交并推送到 GitHub查看当前分支gitbranch --show-current如果不是v4执行gitbranch-Mv4提交gitadd.gitcommit-minit bloggitpush-uorigin v4如果 push 失败报类似remote unpack failed did not receive expected object执行gitpush --no-thin-uorigin v4二十一、开启 GitHub Pages打开你的 GitHub 仓库Settings → Pages找到Build and deployment把 Source 改成GitHub Actions然后进入Actions等待Deploy Quartz site to GitHub Pages变成绿色对勾。成功后访问https://你的用户名.github.io/二十二、解决部署分支限制问题如果 Actions 报错Branch v4 is not allowed to deploy to github-pages due to environment protection rules.解决方法Settings → Environments → github-pages找到Deployment branches and tags把限制改成No restriction或者添加允许部署的分支v4然后回到 Actions点击Re-run jobs重新运行部署。二十三、安装 Obsidian Git 插件打开 Obsidian设置 → 第三方插件 → 浏览搜索Git选择作者是Vinzent描述类似Integrate Git version control with automatic backup安装并启用。注意不要安装GitHobs它主要是 GitHub Issue 编辑器不是我们需要的自动同步插件。二十四、配置 Obsidian Git 自动同步进入设置 → 第三方插件 → Git建议配置Auto commit-and-sync interval10 Auto pull interval10 Auto pull on startup开启 Auto commit-and-sync only staged files关闭 Specify custom commit message关闭 Commit message on auto commit-and-syncvault backup: {{date}} Commit message on manual commitvault backup: {{date}} Merge strategyMerge然后按Ctrl P搜索并执行Git: Commit-and-sync如果显示no change to commit no commits to push说明插件正常只是当前没有新改动。你可以修改content/index.md再执行一次测试。如果显示committed 1 file说明已经成功提交。如果 GitHub 仓库出现新提交并且网站内容也更新了就说明流程完全打通。二十五、配置 .gitignore打开.gitignore建议内容.DS_Store Thumbs.db node_modules/ public/ .quartz-cache/ tsconfig.tsbuildinfo .obsidian/ .trash/ private/ content/private/ .replit replit.nix prof/不要写.gitignore因为.gitignore自己也需要被 Git 管理。如果.obsidian已经被 Git 跟踪执行gitrm-r--cached.obsidiangitcommit-mremove obsidian config from gitgitpush二十六、添加 favicon 网站图标准备一个图标文件icon.png放到quartz/static/icon.png然后本地测试npx quartz build--serve浏览器打开http://localhost:8080如果图标没立刻变化按Ctrl F5或者用无痕窗口查看。确认没问题后Ctrl P → Git: Commit-and-sync二十七、添加 Google Analytics 访问统计27.1 打开 Google Analytics打开https://analytics.google.com/创建账号和媒体资源。如果它问商家信息行业类别互联网与电信 业务规模小型 - 1 至 10 名员工选择数据来源时选择网站 Web网站网址填写注意左边选择 https:// 右边只填 你的用户名.github.io例如mooi-max.github.io不要在右边再写http://或https://。数据流名称可以写Mooi Blog创建完成后复制衡量 ID / Measurement ID格式是G-XXXXXXXXXX27.2 修改 Quartz 配置打开quartz.config.ts找到analytics:{provider:plausible,},或者analytics:null,改成analytics:{provider:google,tagId:G-XXXXXXXXXX,},把G-XXXXXXXXXX换成你自己的衡量 ID。本地测试npx quartz build--serve没报错后同步Ctrl P → Git: Commit-and-sync等 GitHub Actions 部署成功后打开网站再去 Google Analytics 的实时报告查看是否有访问记录。二十八、SEO 优化28.1 站点标题在quartz.config.ts中设置pageTitle:Mooi 的网络安全与技术笔记,28.2 baseUrl确认baseUrl:你的用户名.github.io,例如baseUrl:mooi-max.github.io,28.3 首页描述打开content/index.md顶部写--- title: 首页 description: Mooi 的个人技术笔记记录 CTF、网络安全、Linux、Docker、数据库、工具教程和学习复盘。 ---28.4 文章描述每篇文章顶部建议写--- title: Nmap常用命令 description: 记录 Nmap 在 CTF 和靶机测试中的常用扫描命令、参数说明和实战用法。 date: 2026-04-29 tags: - CTF - Nmap - 信息收集 ---28.5 图片 alt不要写建议写二十九、代码块样式优化打开quartz/styles/custom.scss保留use ./base.scss; // put your custom CSS here!在底部添加/* Code Block Style 简洁代码块样式 */ :not(pre) code { padding: 0.18rem 0.42rem; margin: 0 0.08rem; border-radius: 6px; font-size: 0.88em; font-family: JetBrains Mono, Cascadia Code, Fira Code, Consolas, Menlo, monospace; background: color-mix(in srgb, var(--secondary) 12%, transparent); color: var(--secondary); border: 1px solid color-mix(in srgb, var(--secondary) 18%, transparent); white-space: break-spaces; } pre { position: relative !important; margin: 1.35rem 0; padding: 1.15rem 3.4rem 1.15rem 1.15rem !important; min-height: 3.2rem; border-radius: 14px; overflow-x: auto; overflow-y: visible !important; font-size: 0.92rem; line-height: 1.7; font-family: JetBrains Mono, Cascadia Code, Fira Code, Consolas, Menlo, monospace; background: #1f2933 !important; color: #e5e7eb; border: 1px solid rgba(148, 163, 184, 0.22); box-shadow: 0 10px 24px rgba(0, 0, 0, 0.14), inset 0 1px 0 rgba(255, 255, 255, 0.04); } pre code { display: block; padding: 0 !important; margin: 0 !important; font-size: inherit; line-height: inherit; font-family: inherit; background: transparent !important; color: inherit; border: none !important; white-space: pre; tab-size: 2; } pre span { font-family: inherit; } pre::-webkit-scrollbar { height: 8px; } pre::-webkit-scrollbar-track { background: rgba(255, 255, 255, 0.05); border-radius: 999px; } pre::-webkit-scrollbar-thumb { background: rgba(148, 163, 184, 0.48); border-radius: 999px; } pre::-webkit-scrollbar-thumb:hover { background: rgba(148, 163, 184, 0.78); }以后写代码块时建议写语言名bash nmap -sC -sV 192.168.56.105 sql select * from student; python print(hello) 三十、网站背景优化继续修改quartz/styles/custom.scss在底部添加/* Mooi Blog - Simple Background 暗色科技赛博朋克 亮色明亮暖白 */ html, body { min-height: 100%; } body { background-attachment: fixed; background-repeat: no-repeat; background-position: center top; } /* 暗色模式深蓝黑 蓝紫科技光晕 */ :root[saved-themedark] body { background: radial-gradient(circle at 15% 10%, rgba(34, 211, 238, 0.18), transparent 28rem), radial-gradient(circle at 85% 12%, rgba(168, 85, 247, 0.2), transparent 30rem), radial-gradient(circle at 50% 105%, rgba(59, 130, 246, 0.12), transparent 32rem), linear-gradient(135deg, #050816 0%, #08111f 45%, #111827 100%); } /* 亮色模式明亮暖白不带蓝色光感 */ :root[saved-themelight] body { background: radial-gradient(circle at 16% 10%, rgba(255, 255, 255, 0.95), transparent 28rem), radial-gradient(circle at 86% 12%, rgba(255, 247, 237, 0.55), transparent 30rem), radial-gradient(circle at 50% 105%, rgba(250, 250, 250, 0.92), transparent 32rem), linear-gradient(135deg, #ffffff 0%, #fafafa 50%, #f6f6f4 100%); } /* 暗色模式正文区域轻微玻璃卡片感 */ :root[saved-themedark] article { background: rgba(8, 13, 28, 0.56); border-radius: 16px; border: 1px solid rgba(148, 163, 184, 0.14); box-shadow: 0 14px 36px rgba(0, 0, 0, 0.22); } /* 亮色模式正文区域干净白色卡片感 */ :root[saved-themelight] article { background: rgba(255, 255, 255, 0.78); border-radius: 16px; border: 1px solid rgba(148, 163, 184, 0.14); box-shadow: 0 14px 34px rgba(15, 23, 42, 0.06); } /* 暗色模式标题轻微科技光效 */ :root[saved-themedark] article h1 { text-shadow: 0 0 22px rgba(34, 211, 238, 0.12); } /* 亮色模式标题保持清爽 */ :root[saved-themelight] article h1 { text-shadow: none; }保存后本地测试npx quartz build--serve三十一、图片管理规范建议1. 图片尽量压缩 2. 文件名用英文或拼音 3. 不要用空格和特殊符号 4. 每个目录使用 assets 文件夹推荐content/CTF/assets/nmap-scan-01.png content/Docker/assets/docker-network-01.png content/Linux/assets/linux-permission-01.png不推荐截图 2026-04-29 这个很重要.png三十二、自定义域名说明不买域名也可以正常使用https://你的用户名.github.io/如果以后想买域名域名不能只叫mooi必须是完整域名例如mooi.top mooi.icu mooi.dev mooi.blog如果买的是根域名例如mooi.top需要在 GitHub Pages 填写 Custom domain并在域名服务商添加 DNS 解析。如果使用子域名例如blog.mooi.topDNS 中添加 CNAME 指向你的用户名.github.io三十三、常见问题排查33.1 首页 404检查是否存在content/index.md如果是content/index.md.md改成index.md33.2 GitHub Pages 没更新检查1. GitHub Actions 是否绿色成功 2. Pages Source 是否为 GitHub Actions 3. 浏览器是否需要 Ctrl F5 强制刷新 4. 是否访问了正确的网址33.3 Actions 报 v4 不允许部署解决Settings → Environments → github-pages允许v4分支部署。33.4 Obsidian Git 显示 no change to commit这不是错误。意思是没有新改动需要提交 没有本地提交需要推送修改一篇文章后再执行Git: Commit-and-sync33.5 push 失败 remote unpack failed执行gitpush --no-thin-uorigin v433.6 图片不显示检查1. 图片路径是否正确 2. 图片文件是否真的存在 3. 图片是否提交到了 GitHub 4. 文件名是否有特殊符号33.7 Google Analytics 没数据检查1. tagId 是否是 G- 开头 2. GitHub Actions 是否部署成功 3. 是否打开的是线上网站 4. 是否用了广告拦截插件 5. 是否查看的是实时报告三十四、日常使用流程以后每天写博客只需要1. 打开 Obsidian 2. 在 content 里写文章 3. 插入图片 4. 等 Git 插件自动同步 5. 或手动执行 Git: Commit-and-sync 6. GitHub Actions 自动部署 7. 网站自动更新如果你改了配置文件或样式文件建议先本地测试npx quartz build--serve确认没问题再同步到 GitHub。三十五、最终推荐项目结构myblog/ ├── content/ │ ├── index.md │ ├── CTF/ │ │ ├── index.md │ │ ├── Nmap常用命令.md │ │ └── assets/ │ ├── Linux/ │ │ └── index.md │ ├── Docker/ │ │ └── index.md │ ├── 数据库/ │ │ └── index.md │ ├── 工具教程/ │ │ └── index.md │ └── 随笔/ │ └── index.md ├── quartz/ ├── quartz.config.ts ├── quartz.layout.ts ├── quartz/ │ └── static/ │ └── icon.png ├── .github/ │ └── workflows/ │ └── deploy.yml ├── .gitignore └── package.json到这里你已经拥有一个完整的个人技术笔记博客Obsidian 写作 GitHub 保存 Quartz 构建 GitHub Pages 发布 Obsidian Git 自动同步 Google Analytics 访问统计 favicon 网站图标 SEO 基础优化 代码块样式优化 背景样式优化后面只需要持续写文章即可。