文档网络安全教程【免费下载链接】ctf-wikiCome and join us, we need you!项目地址https://gitcode.com/gh_mirrors/ct/ctf-wiki点击查看免费下载CTF Wiki 是一个面向 CTF 学习者的开源安全知识库其知识文档由社区贡献者共同维护。为了让每一份新增或修改的文档都能与现有站点风格一致、便于检索与长期维护贡献文档要求 明确了贡献文档前必须满足的三类规范内容基本格式、文档合理性、文档存储格式。本文将以该文档为主体结合仓库中实际的目录结构、mkdocs.yml导航配置与 scripts/docs.py 构建脚本逐条展开说明这些要求背后的原因与落地方式帮助你在贡献前一次性通过文档质量检查。概览贡献文档需满足的三项核心要求在开始编写任何文档之前应先阅读 贡献之前 中关于协作方式的说明再对照本文的规范自检。具体而言贡献文档时应当确保文档内容满足基本格式要求——排版风格与站点构建体系一致文档的合理性——内容结构符合由浅入深、逻辑完整的原则文档存储的格式——文件与图片按约定目录、约定命名存放保证仓库可维护性。这三个方面分别对应怎么写写成什么样放在哪里三个问题下面依次展开。文档内容的基本格式要求排版规范中文排版指南与 MkDocs 使用说明文档的排版基准参考项目维护的中文排版指南与 MkDocs 使用说明二者与站点的实际构建方式直接相关。当前仓库使用MkDocs Material 主题这一点可以在各语言版本的配置文件中确认例如 docs/zh/mkdocs.yml 中的theme: name: material以及站点构建所依赖的 requirements.txt 中的 MkDocs 相关依赖。因此贡献者在本地编写文档时使用的 Markdown 语法应当与 MkDocs 支持的扩展保持一致避免引入无法被渲染的写法。标题不加序号为未来自动编号保留空间要求规定不推荐在段落标题处增加序号如1.1 概述2.3 原理这类写法。原因在于项目方之后可能会考虑为段落标题自动生成序号。如果贡献者在标题中手工写入序号一旦启用自动编号机制就会出现重复编号或编号错位的问题届时需要全站批量修改维护成本很高。因此标题只写语义化名称把编号交给站点系统处理。这一点在仓库现有的文档中得到了贯彻——所有章节标题均为纯文字描述例如 MD5 破解 的标题为基本描述破解题目翻译 的标题为完善已有语言新增全新语言均无手工序号。不写题目链接由 ctf-challenge 仓库统一管理文档要求中特别强调所涉及的题目附件都合理地放在了ctf-challenge仓库中因此文档内无需注明题目链接。这样设计有两个现实原因集中管理题目附件统一托管在姊妹仓库ctf-challenge中文档只负责讲解知识不负责承载附件职责边界清晰链接易失效题目附件在仓库中可能随时移动若文档中硬编码了题目链接一旦目录调整修复链接是一件非常费时间的事情。关于如何使用题目附件可参考 如何使用 CTF Wiki以基本 ROP 章节为例附件位于ctf-challenges仓库的pwn/linux/user-mode/stackoverflow目录下按知识模块分目录存放。文档的合理性内容结构必须达到的标准所谓合理性指所编写的内容必须具备以下两个特性确保读者能够循序渐进地掌握知识由浅入深难度渐进文档内容的难度应当具有渐进性从基础概念讲起逐步深入到复杂场景。这保证了零基础读者可以顺着文档路径学习而不是一上来就面对晦涩的攻击手法或高级技巧。以 docs/zh/docs/crypto/hash/md5.md 为例其组织方式正是从 MD5 的输入输出定义讲起再讲特征 IV 的识别方法最后才进入破解手段与题目难度层层递进。逻辑完整原理 → 例子 → 题目对于每类内容的撰写应尽量包含以下三要素要素说明篇幅建议原理说明该内容对应的原理作为正文核心解释为什么例子给出 12 个典型的例子帮助读者建立直观理解题目在该标题下只需要给出题目名字不写链接、不放附件、不贴题解特别注意第三点题目部分只需要给出题目名字既不需要链接见上文不写题目链接也不需要把附件直接放进文档目录。题目对应的附件应统一存放在ctf-challenge仓库的对应目录中。仓库中的文档实践与这一规范完全吻合。以 MD5 破解 为例其题目一节仅列出了两个题目名CFF 2016 好多盐JarvisOJ 好多盐没有附加任何链接或附件说明。文档存储的格式目录与文件命名约定对于每类要编写的内容对应的文档应存储在合适的目录下具体约定如下figure 目录与图片本地化编写文档时使用的图片应存放在figure目录中图片必须放在本地文件夹避免引用外链防止外部图床失效导致文档插图丢失使用相对路径./figure来索引图片例如[](https://link.gitcode.com/i/7f035cd652045a5a8a8b4d118337be6c)这样文档无论在哪一层目录都能正确解析。这一约定在仓库中得到了严格执行几乎每个知识章节目录下都有figure/子目录例如 docs/zh/docs/crypto/blockcipher/mode/figure、docs/zh/docs/misc/picture/figure、docs/zh/docs/introduction/figure 等图片资源与文档就近存放。文件名规范小写 -分割文件名请务必都小写以-分割例如file-name。这一约定的意义在于跨平台一致性避免大小写敏感文件系统如 Linux与大小写不敏感文件系统如 macOS/Windows之间的路径匹配差异URL 友好性MkDocs 生成的站点 URL 直接来源于文件名全小写 连字符的命名在搜索引擎中更友好也更便于读者记忆和直接输入排序稳定性统一命名规则后目录列表与导航树的排序结果可预期。仓库中符合该约定的文件名随处可见例如 docs/zh/docs/contribute/basic-contribute-approach.md、docs/zh/docs/pwn/linux/kernel-mode/basic-knowledge.md、docs/zh/docs/misc/traffic/protocols/wireshark.md 等。附件统一存放于 ctf-challenge 仓库无论是例子还是题目相应的附件都应该存储在ctf-challenge仓库中的对应目录而不是直接放入 ctf-wiki 文档仓库。这样保证了文档仓库保持轻量只包含文字与少量插图题目与附件由专门的仓库统一归档便于按模块查找附件更新如题目重打包不需要改动文档本身避免产生无意义的提交历史。仓库中的落地验证规范如何被强制执行与检查上述规范不是孤立的写作建议而是与仓库的构建与多语言体系深度耦合的。理解下面的工程细节有助于贡献者在提交前自检。多语言目录结构当前仓库在docs/下按语言代码组织多个独立站点docs/zh —— 简体中文默认语言default_lang zh见 scripts/docs.pydocs/en —— 英文docs/zh-tw —— 繁体中文。每种语言目录下都有各自的docs/内容目录、overrides/覆盖目录与mkdocs.yml配置文件。文件级的翻译对齐规则由 翻译规范 说明翻译只需保证不同语言在文件级别上保持一致具体内容意思表达一致即可不必逐字逐句。mkdocs.yml 导航树与文档路径的一致性每份新增文档都必须在对应语言的 mkdocs.yml 的nav中注册才能出现在站点导航中。以贡献指南为例其导航配置如下nav: - Start: - index.md - usage.md - 贡献指南: - contribute/before-contributing.md - contribute/basic-contribute-approach.md - contribute/documentation-requirement.md - contribute/translation.md - discussion.md可见nav中引用的路径必须与docs/目录下的实际文件路径严格一致均以docs/为根不带目录前缀任何文件移动或重命名都需要同步更新导航配置这正是命名规范需要严格遵守的原因之一——不规范的命名会让导航维护与链接修复变得更加困难。构建脚本对缺失翻译的处理scripts/docs.py 是站点构建的核心工具其build_lang命令见 scripts/docs.py#L122-L230会为尚未翻译的语言版本自动生成占位页当某个文件在目标语言中缺失时脚本读取中文原文并在其后插入 docs/missing-translation.md 中的尚未翻译提示片段对应函数get_text_with_translate_missing见 scripts/docs.py#L416-L423。这意味着只要文件在nav中注册且中文版本存在任何语言站点都不会出现 404 页面。也正因为如此文件名的稳定性格外重要——一旦文件名变更所有语言版本中对该文件的引用都需要同步调整。该脚本还支持以下常用命令基于 Typer 编写先安装 requirements.txt 中的依赖# 以实时预览方式启动指定语言的站点默认 zh端口 127.0.0.1:8008 python3 scripts/docs.py live en # 初始化一种全新的语言如日语 jp python3 scripts/docs.py new-lang jp # 构建默认语言并依次构建其他语言到 ./site/ python3 scripts/docs.py build-all贡献者在本地完成修改后可通过python3 scripts/docs.py live lang预览站点效果确认页面渲染符合预期这也是 基本贡献方式 中强调的在本地可以正常生成文档的要求。贡献前自检清单综合以上规范提交一份文档贡献前请逐项核对内容格式排版遵循中文排版指南与 MkDocs 使用说明段落标题未加手工序号为未来自动编号保留空间正文中没有硬编码的题目链接题目附件由 ctf-challenge 仓库承载内容合理性难度由浅入深具备渐进性每类内容包含原理 12 个例子 题目名称三要素题目部分只给题目名字不贴链接、不放附件存储格式图片存放在本地figure/目录使用相对路径./figure引用无外链文件名全小写、以-分割如file-name.md例子与题目的附件已提交到 ctf-challenge 仓库的对应目录新增文件已在对应语言的 mkdocs.ymlnav中注册本地运行python3 scripts/docs.py live lang确认站点渲染正常完成以上检查后即可按照 基本贡献方式 提交 Pull Request。规范的意义不在于限制创作而在于让成千上万个页面在长期迭代中依然保持统一的阅读体验与可维护性——这正是 CTF Wiki 能够持续积累、被读者信赖的根基。赞分享文档网络安全教程【免费下载链接】ctf-wikiCome and join us, we need you!项目地址https://gitcode.com/gh_mirrors/ct/ctf-wiki点击查看免费下载相关推荐CTF Wiki 贡献文档规范格式、结构与存储路径的完整指南CTF Wiki 贡献文档规范格式、结构与存储路径的完整指南 CTF Wiki 是一个面向 CTFCapture The Flag学习者的开源知识库其内文档网络安全教程CTF Wiki 贡献文档规范内容格式、结构逻辑与文件路径存储指南CTF Wiki 贡献文档规范内容格式、结构逻辑与文件路径存储指南 导读 本文是对 CTF Wiki 开源仓库中 贡献文档要求 https://link.gi文档网络安全教程为 Foam 编写 Recipe从文档结构规范到贡献合入的完整指南为 Foam 编写 Recipe从文档结构规范到贡献合入的完整指南 本篇指南以 Foam 官方文档 how to write recipes.md https知识管理知识库开发工具MCP 服务上一篇Ory Keto版本升级终极指南从旧版本迁移到新版本的完整流程下一篇CocoIndex入门指南15分钟打造你的智能数据索引系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考