[project-based-learning] docs | 教程列表 | 格式规范 | 锚点分类体系
链接：https://github.com/practical-tutorials/project-based-learning
docs：基于项目的学习
本项目是一个精选的项目列表，包含通过构建实际应用程序学习编程的在线教程。
教程按编程语言分类，帮助用户轻松找到相关项目。
同时提供贡献指南用于添加新教程，并使用自动化检查确保链接始终有效。
可视化概览
章节
- 教程列表
- 教程条目格式
- 项目分类
- 贡献指南
- 自动化链接验证
- 问题模板
第1章：教程列表
欢迎来到基于项目的学习！
这是理解本项目如何帮助我们成为更优秀程序员的第一步。
那么，本项目究竟是什么呢？
-
假设你想学习一门新编程语言（例如Python），但不只是想阅读书籍或观看讲座。
-
想要
构建真正可用的项目，比如自己的博客或简单游戏。 -
通过实践学习是掌握实用技能的绝佳方式！
但哪里能找到真正指导从零开始构建完整应用程序的优秀指南呢？
-
网上有海量教程，但筛选出合适的基于项目的教程可能非常困难。
-
这正是本项目的核心理念诞生之处：教程列表。
什么是「教程列表」？
将"教程列表"想象成一个特殊的图书馆目录，但这里存储的是指导我们构建实用项目的在线编程教程。
它不是书架上的书籍，而是一系列在线指南链接，这些指南将带你完整创建应用程序或系统。
主要目标很简单：为有抱负的开发者提供一个便捷平台，通过构建来学习不同技术。
列表如何帮助我们
回到我们的示例：想通过构建博客学习Python。该如何使用此列表？
可在Python教程专区查找。
在该区域内，会发现一系列链接，每个链接都指向使用Python构建特定项目的教程。可以浏览列表寻找"构建博客"或"创建Web应用"等条目。
列表主要按教程使用的主要编程语言进行组织，便于快速查找目标语言的项目。
列表存储位置
列表本身存放在项目的根文件README.md中。当在GitHub查看项目页面时，首先看到的就是这个README.md文件的内容。
以下是README.md的简化示例（完整列表请查看项目主文件）：
# 基于项目的学习程序员通过构建完整应用学习的教程列表。这些教程按主要编程语言分类，可能涉及多种技术和语言。开始使用时，请先fork本仓库。贡献指南请参考[CONTRIBUTING.md](CONTRIBUTING.md)。## 目录:- [C#](#c)
- [C/C++](#cc)
- [Clojure](#clojure)
- [Dart](#dart)
- [Elixir](#elixir)
...
- [Python](#python)
...## Python:### Web应用:- [使用Flask构建微博客](https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world)
- [使用Django创建博客Web应用](https://tutorial.djangogirls.org/en/)
...
看出规律了吗？
目录链接到不同语言专区，每个语言板块（## Python:）下列出教程条目（- [使用Django创建博客Web应用](https://tutorial.djangogirls.org/en/)）。
每个列表项都是在线教程的链接。
底层原理（非常简单！）
这个列表如何运作？实际上非常直观。
-
它只是一个使用Markdown格式编写的文本文件（
README.md）。Markdown是通过符号（如#表示标题，-表示列表项，[文本](链接)表示超链接）实现文本格式化的简易方法。 -
点击
README.md中的链接时，浏览器会直接跳转托管教程的网站。 -
本项目不托管教程，仅为其提供索引。
以下是使用列表的简易流程：
这就像在图书馆目录中找到书名后去书架上取书（当前场景是点击链接访问网站）。
总结
了解到基于项目的学习项目的核心是"教程列表"——按编程语言组织的实用编程教程链接合集。
看到该列表存在于README.md文件中，并学会了如何浏览列表寻找感兴趣的项目。这个简洁的系统旨在通过构建学习的方式，为连接优质资源。
现在已了解列表机制，接下来让我们深入探究列表中每个条目的编写规范。
教程条目格式
第二章：教程条目格式规范
欢迎回到project-based-learning教程！在上一章《教程列表》中，我们发现了本项目的核心：一个精心整理的基于项目的编程教程清单，这些教程都收录在README.md文件中。
我们了解了该列表是如何按编程语言分类并包含外部网站链接的。
现在，让我们聚焦于列表中的单个条目。当我们查看README.md时，会看到如下条目：
- [用Flask构建微型博客](https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world)
有时也会看到这种形式：
- 编写C语言编译器- [第一部分：整数、词法分析与代码生成](https://norasandler.com/2017/11/29/Write-a-Compiler.html)- [第二部分：一元运算符](https://norasandler.com/2017/12/05/Write-a-Compiler-2.html)...
这些并非随意文本，它们遵循特定的结构规范。本章将全面解析教程条目格式。
为何需要统一格式？
试想如果每个人都能随意添加教程链接。
-
有人可能直接粘贴原始链接，有人使用
不同的列表格式，还有人使用短链接服务。README.md文件将很快变得混乱不堪、难以阅读和维护。 -
教程条目格式规范正是为了解决这个问题。它为
README.md中的每个教程链接提供了清晰一致的编写规则，使列表易于所有人阅读理解，这也是贡献教程链接时的必要前提（我们将在《贡献指南》中详细说明）。
该格式的核心使用场景是：如何正确地将单个教程或多部分系列教程添加到README.md列表中？
让我们分解格式要求。
基础链接格式
最常见的教程列表形式是使用Markdown链接语法结合列表项。
标准格式：
- [教程标题](教程链接)
各组成部分解析：
-：Markdown的列表项符号，显示时会生成项目符号（•）[教程标题]：显示在README.md中的可点击文本，应为描述性标题（如"用Flask构建微型博客"）(教程链接)：教程的实际网络地址（URL）
示例：
- [用C语言编写Shell程序](https://brennan.io/2015/01/16/write-a-shell-in-c/)
GitHub渲染效果：
• 用C语言编写Shell程序
添加单个教程时，只需在对应语言分区（可能包含"Web应用"等子类）下新建以- 开头的行，依次填写标题和链接。
多部分系列格式
当教程分为多个章节时，需要将所有部分归组显示：
标准格式：
- 系列总标题- [章节1标题](章节1链接)- [章节2标题](章节2链接)- [章节3标题](章节3链接)...
组成部分解析：
- 系列总标题：作为整个系列的主列表项（无链接）- 缩进的
- [章节X标题](章节X链接)：使用两个空格或制表符缩进，每个章节遵循基础链接格式
示例：
- 用Go构建区块链- [第一部分：基础原型](https://jeiwan.net/posts/building-blockchain-in-go-part-1/)- [第二部分：工作量证明](https://jeiwan.net/posts/building-blockchain-in-go-part-2/)- [第三部分：持久化与CLI](https://jeiwan.net/posts/building-blockchain-in-go-part-3/)...
GitHub渲染效果：
• 用Go构建区块链
• 第一部分：基础原型
• 第二部分：工作量证明
• 第三部分：持久化与CLI
…
重要链接规范
关于链接部分的核心规则：
- 必须直接指向教程页面，
禁止使用URL短链接服务
原因：
- 透明性：点击前可预览真实域名
- 持久性：短链接服务可能失效
- 安全性：避免隐藏恶意链接
例外情况：
- 原始URL超过80字符时，可能允许使用短链接（但建议优先使用原始链接）。注：原始指南提及的Google短链接服务已停用，当前建议仍以
直接链接为主
幕后机制：Markdown渲染
README.md如何转换为美观的网页？其过程可通过序列图表示：
该过程本质上是GitHub的Markdown解析器将符号转换为HTML代码的过程。
总结
本章核心要点：
- 单教程格式：
- [标题](链接) - 系列教程格式：主标题+缩进章节
- 链接规范：优先使用
原始链接
遵循该格式对维护教程列表质量至关重要。
下一章《项目分类》将讲解如何为教程选择正确的分类位置。
第三章：项目分类体系
欢迎回来！在上一章《教程条目格式规范》中，我们学习了如何在README.md文件中编写独立教程链接的Markdown规范，无论是单篇教程还是系列教程。
既然已掌握如何编写教程条目，接下来需要理解的核心概念是这些条目在README.md中的定位方式。面对数百个教程条目，若全部混杂在单一列表中，将极大降低浏览效率！
本章将深入解析项目分类体系——如何通过结构化组织使教程更易检索。
为何需要分类体系？
-
试想走进一座所有书籍随意堆砌的图书馆，寻找特定书籍将异常困难！
-
同理，如若
project-based-learning的README.md文件仅是杂乱无章的长链接列表，用户将难以快速定位目标教程。
分类体系解决的核心问题是：如何快速找到使用特定编程语言/技术的项目教程？
解决方案清晰明了：采用图书馆式的分类体系，按技术领域划分教程。
(像我们之前文章当中讲到的[OS_25] 应用数据的存储，数据库其实也是一种对于数据的分类。还有在当今AI时代下，未来发展趋势的向量索引，就是以问题为导向的查询)
主分类维度：编程语言
本项目主要采用编程语言作为一级分类维度。
这种划分符合用户常规检索逻辑——开发者往往基于目标语言筛选教程。
在README.md中，每个主编程语言对应独立分区，使用Markdown二级标题（##）标注。以下是源文件结构示例：
## C/C++:... C/C++教程列表 ...## C#:... C#教程列表 ...## Clojure:... Clojure教程列表 ...## Dart:... Dart教程列表 ...... 其他语言分区 ...## Python:... Python教程列表 ...## Ruby:... Ruby教程列表 ...
GitHub渲染时，## 语言名称:会转换为醒目的分区标题。
快捷导航：目录系统
为提升检索效率，README.md文件起始处设有目录章节。该目录包含指向各语言分区的锚点链接。
目录片段示例：
## 目录:- [C#](#c)
- [C/C++](#cc)
- [Clojure](#clojure)
- [Dart](#dart)
- [Elixir](#elixir)
...
- [Python](#python)
...
每条形如- [Python](#python)的条目实为Markdown锚点链接：
-：列表项标识符[Python]：目录中显示的可点击文本(#python)：锚点定位标识符，指向页面内ID为python的HTML元素（对应## Python:标题）
点击目录中的"Python"链接，浏览器将自动滚动至## Python:分区。
子分类体系（三级标题）
当某编程语言包含多个技术方向的教程时（如Web开发、数据科学、游戏开发等），需使用三级标题（###）建立子分类。
以Python分区为例：
## Python:### 网络爬虫:... Python爬虫教程 ...### Web应用:... Python Web应用教程 ...### 机器人开发:... Python机器人教程 ...### 数据科学:... Python数据科学教程 ...... 更多子类 ...
###标题会生成略小于二级标题的视觉层级，实现内容分组。
分类体系应用实例
假设您想通过构建Web应用来学习JavaScript，检索流程如下：
- 访问
project-based-learning的GitHub页面，打开README.md - 查看顶部的目录章节
- 在目录中定位**“JavaScript”**条目
- 点击"JavaScript"锚点链接，自动跳转至
## JavaScript:分区 - 在JavaScript分区内查找
### Web应用子分类 - 浏览该子分类下的教程列表（
-开头的条目） - 根据标题选择感兴趣的教程并访问链接
这种结合目录导航（锚点链接）、主分类（二级_编程语言）和子分类（三级_方向）的结构化体系，显著提升了长文档的浏览效率。
底层原理：Markdown标题与锚点
目录导航的实现依赖Markdown标题的自动化处理，锚点导航原理：
关键处理流程：
- 标题转换：Markdown的
## 标题转换为HTML的<h2 id="标题">元素，自动生成唯一ID - 锚点链接：目录中的
[链接](#标题)转换为<a href="#标题">，点击后浏览器定位对应ID元素
这是标准的网页锚点导航机制，有效解决了长文档定位难题。
总结
本章解析了project-based-learning教程列表的分类体系：
- 主分类维度：按编程语言划分（二级标题
##） - 子分类体系：按技术方向细分（三级标题
###） - 导航系统：目录章节使用锚点链接实现快速跳转
掌握该分类体系后，我们已具备高效使用教程列表的能力。接下来我们将进入最重要的环节——了解如何为项目贡献优质教程！让更多的人参与到其中来做贡献~
贡献指南