★ FEATURED ARTICLE 1. 为什么你需要一个基于Teedoc的个人知识库在这个信息爆炸的时代我们每天接触的知识量远超大脑的处理能力。作为一名长期与技术文档打交道的开发者我深刻体会到知识管理的重要性。传统的笔记工具如OneNote或Evernote虽然方便但缺乏结构化展示和版本控制能力而Wiki系统又过于笨重。直到我发现了Teedoc这个开源静态网站生成器它完美解决了我的痛点。Teedoc基于Python开发使用Markdown编写内容通过Git进行版本管理最终生成静态HTML网站。这种组合带来了几个显著优势完全离线可用不像Notion等云端工具你的知识不会因为网络问题而无法访问版本控制友好所有内容都是纯文本文件可以完美配合Git管理历史版本高度可定制主题、插件、布局都可以自由调整多设备同步通过Git仓库可以轻松在多个设备间同步知识库我使用Teedoc搭建个人知识库两年多整理了超过300篇技术笔记涉及前端开发、服务器运维、数据分析等多个领域。这个系统帮助我在跳槽面试时快速回顾知识点在新项目中快速查找历史解决方案效率提升非常明显。2. 环境准备与Teedoc安装2.1 基础环境配置在开始之前我们需要准备以下环境Python 3.7Teedoc是基于Python的工具Node.js 12部分插件需要JavaScript环境Git用于版本控制和内容同步对于Windows用户我推荐使用Scoop包管理器一键安装scoop install python nodejs gitmacOS用户可以使用Homebrewbrew install python node gitLinux用户以Ubuntu为例sudo apt update sudo apt install python3 python3-pip nodejs git注意Python环境建议使用虚拟环境隔离避免与系统Python环境冲突。可以使用以下命令创建虚拟环境python -m venv teedoc-env source teedoc-env/bin/activate # Linux/macOS teedoc-env\Scripts\activate # Windows2.2 Teedoc核心安装安装好基础环境后通过pip安装Teedocpip install teedoc验证安装是否成功teedoc --version如果看到版本号输出如1.0.0说明安装成功。我建议同时安装以下常用插件pip install teedoc-plugin-theme-default teedoc-plugin-breadcrumb3. 项目初始化与目录结构解析3.1 创建知识库项目选择一个合适的目录执行初始化命令teedoc init my_knowledge_base cd my_knowledge_base这会生成以下目录结构my_knowledge_base/ ├── .teedoc_config.yml # 全局配置文件 ├── docs/ # 文档目录 │ ├── images/ # 图片资源 │ └── index.md # 首页文档 ├── site_config.json # 站点配置 └── teedoc-template/ # 模板文件3.2 关键配置文件详解site_config.json是核心配置文件主要字段包括{ name: My Knowledge Base, root_url: /, languages: { zh: 中文, en: English }, theme: { default: { plugin: teedoc-plugin-theme-default, config: { dark: true, sidebar_show: always } } }, plugins: { breadcrumb: { plugin: teedoc-plugin-breadcrumb } } }我通常会做以下定制启用暗黑模式dark: true设置侧边栏始终显示sidebar_show: always添加Google Analytics跟踪需额外配置3.3 编写第一篇文档编辑docs/index.md文件# 欢迎来到我的知识库 这是我的个人知识库记录技术学习和工作心得。 ## 分类导航 - [编程语言](/lang/) - [系统运维](/ops/) - [算法与数据结构](/algorithms/)创建分类目录mkdir -p docs/lang docs/ops docs/algorithms每个分类下创建README.md作为入口文件echo # 编程语言笔记 docs/lang/README.md echo # 系统运维笔记 docs/ops/README.md echo # 算法与数据结构 docs/algorithms/README.md4. 高级功能与定制化4.1 多语言支持Teedoc原生支持多语言配置方法在site_config.json中定义支持的语言创建对应语言的文档目录例如添加英文支持languages: { zh: 中文, en: English }然后创建英文文档结构mkdir -p docs/en/{lang,ops,algorithms} echo # My Knowledge Base docs/en/index.md4.2 自定义主题样式创建assets/css/custom.css文件:root { --primary-color: #4285f4; --sidebar-width: 280px; } .content-wrapper { max-width: 1200px; }在site_config.json中引用theme: { default: { plugin: teedoc-plugin-theme-default, config: { css: /assets/css/custom.css } } }4.3 数学公式与图表支持通过插件支持LaTeX公式和Mermaid图表安装插件pip install teedoc-plugin-katex teedoc-plugin-mermaid配置site_config.jsonplugins: { katex: { plugin: teedoc-plugin-katex }, mermaid: { plugin: teedoc-plugin-mermaid } }在Markdown中使用mermaid graph TD A[开始] -- B(处理请求) B -- C{成功?} C --|是| D[返回结果] C --|否| E[记录错误] 行内公式$Emc^2$ 块级公式 $$ \int_a^b f(x)dx F(b) - F(a) $$5. 构建与部署实战5.1 本地构建与预览执行构建命令teedoc build构建完成后会在out目录生成静态网站。本地预览teedoc serve访问 http://localhost:8080 查看效果。5.2 自动化部署到GitHub Pages在GitHub创建新仓库初始化本地Git仓库git init git add . git commit -m init git branch -M main git remote add origin gitgithub.com:yourname/yourrepo.git git push -u origin main创建GitHub Actions工作流文件 .github/workflows/deploy.ymlname: Deploy on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Set up Python uses: actions/setup-pythonv2 with: python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip pip install teedoc - name: Build run: teedoc build - name: Deploy uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./out在仓库Settings中启用GitHub Pages选择gh-pages分支5.3 自定义域名配置在out目录创建CNAME文件写入你的域名mydomain.com在DNS服务商处添加CNAME记录指向GitHub Pages地址在site_config.json中配置root_urlroot_url: https://mydomain.com,6. 知识管理的最佳实践6.1 内容组织策略经过多次迭代我总结出以下目录结构方案docs/ ├── 01-编程语言/ │ ├── Python/ │ ├── JavaScript/ │ └── Go/ ├── 02-系统运维/ │ ├── Linux/ │ ├── Docker/ │ └── Kubernetes/ ├── 03-工具链/ │ ├── Git/ │ └── VSCode/ └── 04-个人项目/ ├── 项目A/ └── 项目B/编号前缀01-, 02-保证排序每个分类下按技术细分。README.md作为分类入口_sidebar.md自定义侧边栏。6.2 高效写作技巧Markdown扩展语法使用::: tip等容器块高亮内容通过[[TOC]]自动生成目录使用!!! note等提示块文档元信息 在文档开头添加YAML front matter--- title: Python虚拟环境详解 date: 2023-08-20 tags: [Python, 虚拟环境] ---交叉引用 使用相对路径链接其他文档详见[Python包管理](/01-编程语言/Python/package.md)6.3 自动化工作流自动构建检查 在GitHub Actions中添加Markdown lint检查- name: Lint Markdown uses: docker://avtodev/markdown-lint:v1 with: args: docs/**/*.md内容自动同步 使用rsync同步到服务器rsync -avz --delete out/ userserver:/var/www/knowledge定期备份 设置cron任务备份到云存储0 3 * * * tar -czf ~/backups/knowledge-$(date \%Y\%m\%d).tar.gz ~/my_knowledge_base7. 常见问题与解决方案7.1 构建错误排查问题1ModuleNotFoundError: No module named teedoc原因Python环境问题解决python -m pip install --upgrade pip pip install teedoc问题2中文内容乱码原因文件编码不是UTF-8解决确保所有.md文件保存为UTF-8编码在site_config.json中添加charset: utf-87.2 性能优化技巧图片优化使用WebP格式替代PNG/JPG安装imageoptim等工具压缩图片懒加载图片{:loadinglazy}减少构建时间使用--incremental参数增量构建teedoc build --incremental排除不需要的目录build: { exclude: [temp/, drafts/] }7.3 搜索功能增强默认主题提供基础搜索如需更强大功能安装Algolia搜索插件pip install teedoc-plugin-search-algolia配置site_config.jsonplugins: { search: { plugin: teedoc-plugin-search-algolia, config: { app_id: YOUR_APP_ID, api_key: YOUR_API_KEY, index_name: knowledge_base } } }生成索引并上传teedoc algolia8. 从知识库到个人品牌8.1 内容SEO优化元标签配置 在site_config.json中添加html: { meta: { description: 我的技术知识库分享编程、运维等领域的学习笔记, keywords: 编程,技术,学习笔记,知识管理 } }生成sitemap 安装插件pip install teedoc-plugin-sitemap配置plugins: { sitemap: { plugin: teedoc-plugin-sitemap, config: { hostname: https://mydomain.com } } }8.2 访客互动功能添加评论系统 使用Gitalk或Utterancesscript srchttps://utteranc.es/client.js repoyourname/yourrepo issue-termpathname themegithub-light crossoriginanonymous async /script访问统计 使用Google Analytics或Umamiscript async srchttps://analytics.umami.is/script.js >a hrefhttps://www.buymeacoffee.com/yourname target_blank img srchttps://cdn.buymeacoffee.com/buttons/v2/default-yellow.png altBuy Me A Coffee height40 /a付费专栏 使用GitHub Sponsors或Patreon提供高级内容广告投放 申请Google AdSense或加入Carbon Ads经过两年多的实践我的Teedoc知识库已经积累了超过500篇技术文档日均访问量稳定在200。这个系统不仅帮助我整理知识还成为了我的个人技术品牌展示窗口甚至带来了工作机会和合作邀约。最重要的是所有内容完全在我的掌控中不用担心服务关闭或数据丢失。
阅读完成 · 觉得有帮助？
