文档教程【免费下载链接】learnxinyminutes-docsCode documentation written as code! How novel and totally my idea!项目地址https://gitcode.com/gh_mirrors/le/learnxinyminutes-docs点击查看免费下载Learn X in Y Minuteslearnxinyminutes-docs是一个以可运行的带注释代码形式讲解编程语言与工具的开源文档仓库本指南面向想要向该仓库提交内容的贡献者完整覆盖贡献流程、写作风格规范、Frontmatter 头部元数据配置、语法高亮与编码要求以及如何在本地构建站点预览自己的文章。读完本文你将能按照仓库的既定规范撰写或翻译一篇教程、正确填写元数据、通过仓库自带的 lint 校验并构建出可浏览的本地站点。贡献的基本原则与流程CONTRIBUTING.md 明确欢迎一切形式的贡献从最小的拼写修正到一篇全新的文章都在接受范围内多语言翻译同样欢迎甚至不限于翻译——任何语言的原创文章都可以。提交方式不限时间随时可以通过 Pull RequestPR或 Issue 提出。为了帮助维护者快速定位与自己相关的提交仓库要求在 Issue 和 PR 的标题前加上[language/lang-code]标签例如英文 Python 教程写作[python/en]中文 Python 教程写作[python/zh-cn]等。这个约定在 README.md 的 Contributing 一节中同样被强调属于提交时的硬性规范。此外如果一次提交涉及多个重大变更例如同时翻译两种不同语言的文章强烈建议为每个变更单独发起一个 PR这样审查者可以更有效地逐个审阅也便于单独合并。写作风格规范Style Guidelines仓库对文章写作风格提出了四条明确要求这些要求共同保证了所有教程在排版和表达上的统一性行宽不超过 80 字符代码块内的行长度应控制在 80 字符以内否则文本会在渲染时溢出影响阅读体验。这一约束以及下文其他格式一致性问题由 markdownlint 这类工具识别。示例优先于说明尽量用最少的文字表达所有场景下都优先使用代码示例而非大段叙述。这正是本仓库的核心形态每篇教程本身就是一份带注释的、可运行的代码。避免赘述Eschew surplusage仓库欢迎新手但目标读者是有一定经验的程序员。因此应避免解释与语言本身无关的基础概念只解释该语言特有的知识点。文章要保持简洁、可快速扫读——正如文档所说我们都知道怎么用 Google。统一使用 UTF-8 编码所有 Markdown 文件必须使用 UTF-8 编码这一要求由仓库自带的 lint 脚本强制执行详见下文编码与格式校验一节。Frontmatter 头部元数据配置站点会从这些 Markdown 文件生成 HTML 页面而 Markdown 正文之前可以包含一段额外的元数据称为frontmatter。它采用 YAML 格式夹在两条---分隔线之间位于文件最顶部。英文编程语言文章必填字段name编程语言的人类可读名称如Ruby、Pythoncontributors贡献者名单是一个由[*作者*, *URL*]组成的列表其中 URL 可选。可选字段category文章分类目前可选值为language语言、tool工具或Algorithms Data Structures算法与数据结构省略时默认为language。实际仓库中amd.md、awk.md、docker.md 等使用category: tooldynamic-programming.md 使用category: Algorithms Data Structuresfilename文章代码对应的文件名站点会抓取该文件、拼接合并并提供下载。翻译文章附加字段translators译者名单同样是[*译者*, *URL*]列表URL 可选。非英文文章会继承对应英文文章如果存在的 frontmatter 值但可以覆盖。这一特性在仓库中有大量实例例如 zh-cn/python.md 只声明了contributors和translators正文则是完整的中文翻译而 bf.md 额外使用了where_x_eq_name: brainfuck这一字段frontmatter 校验脚本允许的键之一用于把文件名中的通配符映射到具体语言名。官方示例Ruby 的头部配置CONTRIBUTING.md 给出的标准示例--- name: Ruby filename: learnruby.rb contributors: - [Doktor Esperanto, http://example.com/] - [Someone else, http://someoneelseswebsite.com/] ---对照仓库中真实的 ruby.md 文件其 frontmatter 结构完全一致name: Ruby、filename: learnruby.rb并带有一长串contributors列表每个成员都是一个[姓名, URL]二元组。这就是一篇标准教程头部的实际形态。Frontmatter 的源码级校验规则为了让贡献者提前发现 frontmatter 错误仓库在 lint/frontmatter.py 中实现了一套自动校验器其核心规则与写作规范一一对应允许的键白名单仅允许name、where_x_eq_name、category、filename、contributors、translators这六个键出现其他键会报Invalid keys found错误lint/frontmatter.py键的类型约束name、where_x_eq_name、category、filename必须是字符串contributors和translators必须是列表lint/frontmatter.py列表成员结构约束contributors/translators中的每一项本身必须是列表长度为 1 或 2第一项必须是字符串作者/译者名第二项如果存在也必须是字符串URLlint/frontmatter.pyYAML 语法检查frontmatter 内容会先经 yamllint 做语法级 lint并关闭了缩进、行宽等与元数据无关的规则再进行上述结构校验lint/frontmatter.py。该脚本既可以针对单个文件运行也可以递归处理整个目录下的所有.md文件lint/frontmatter.py任何文件出错时进程以非零码退出便于接入 CI。运行它所需的依赖记录在 lint/requirements.txt 中仅有yamllint与pyyaml两个包。语法高亮与编码要求语法高亮使用 Pygments站点使用 Pygments 进行代码语法高亮因此文章代码块的语言标识需要能被 Pygments 识别。这意味着在 Markdown 代码围栏中应使用 Pygments 支持的 lexer 名称如ruby、python、bf等以保证渲染后的高亮效果正确。编码与 BOM 校验脚本仓库的 lint/encoding.sh 提供了另一层质量保障它并行检查所有.md文件使用file -b --mime-encoding读取文件编码仅允许utf-8与us-ascii两种lint/encoding.sh若文件为 UTF-8则进一步检查文件开头是否带有 UTF-8 BOMEF BB BF一旦发现 BOM 即报错lint/encoding.sh。这与风格规范中统一使用 UTF-8的要求互为印证规范文字负责说明为什么lint 脚本负责给出怎么查。脚本默认以当前目录为参数也支持传入指定目录lint/encoding.sh。是否把自己加入贡献者名单如果你希望把自己加入contributors字段请记住贡献者列表是平权的equal billing而第一位贡献者通常是整篇文章的作者。因此请自行判断你的贡献是否构成实质性的内容增补再决定是否署名避免将细微改动也列入名单。本地构建站点并预览CONTRIBUTING.md 提供了完整的本地构建流程用于在提交前预览文章的实际渲染效果安装 PythonmacOS 可用 Homebrew 安装brew install python克隆两个仓库站点工程与文档仓库本仓库并将文档仓库嵌套克隆进站点工程的源码目录# 克隆站点工程 git clone https://github.com/adambard/learnxinyminutes-site # 克隆本文档仓库替换为你的用户名嵌套进站点工程 git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./learnxinyminutes-site/source/docs/安装依赖并运行构建cd learnxinyminutes-site pip install -r requirements.txt启动本地 HTTP 服务python build.py cd build python -m http.server在浏览器中访问http://localhost:8000/即可查看渲染后的站点。从源码结构看站点生成逻辑位于learnxinyminutes-site工程内文档仓库只是其source/docs/目录下的内容源而本仓库自带的 lint/ 目录则承担了提交前的静态校验职责二者共同构成了本地预览 自动校验的完整工作流。对于本仓库的日常使用你可以在任意时刻直接运行 lint/frontmatter.py 校验全部 Markdown 文件的元数据运行 lint/encoding.sh 校验全部文件的编码两者结合即可在提交 PR 前完成一次全面的格式自检。赞分享文档教程【免费下载链接】learnxinyminutes-docsCode documentation written as code! How novel and totally my idea!项目地址https://gitcode.com/gh_mirrors/le/learnxinyminutes-docs点击查看免费下载相关推荐Learn X in Y Minutes 项目文档Learn X in Y Minutes 项目文档 1. 项目目录结构及介绍 learnxinyminutes docs 项目是一个开源文档项目旨在为各种编程文档教程从Python到RustLearn X in Y Minutes教程风格解析从Python到RustLearn X in Y Minutes教程风格解析 本文深入分析了Learn X in Y Minutes项目中不同编程语言教程的教文档教程Tsukimi 贡献指南从翻译、本地开发构建到 AI 贡献规范Tsukimi 贡献指南从翻译、本地开发构建到 AI 贡献规范 Tsukimi 是一个使用 GTK4 RS 与 libadwaita 编写的第三方 Jelly桌面应用音视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考