https://www.leanku.com/tags/%E6%96%87%E6%A1%A3%E8%A7%84%E8%8C%83/Recent content in 文档规范 on Leanku 的博客Hugozh-cnThu, 03 Apr 2025 00:00:00 +0000https://www.leanku.com/post/projectmanagement/markdown-writing-guide/Thu, 03 Apr 2025 00:00:00 +0000https://www.leanku.com/post/projectmanagement/markdown-writing-guide/<h2 id="1-文件规范">1. 文件规范</h2> <h3 id="11-文件扩展名">1.1 文件扩展名</h3> <p>Markdown 文件必须使用 <code>.md</code> 扩展名。</p> <p>正确：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">docker-installation.md </span></span><span class="line"><span class="cl">docker-compose.md </span></span><span class="line"><span class="cl">mysql-index.md </span></span></code></pre></div><p>错误：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">docker-installation.markdown </span></span><span class="line"><span class="cl">docker-installation.txt </span></span></code></pre></div><h3 id="12-文件名">1.2 文件名</h3> <p>文件名统一使用小写字母。</p> <p>多个单词之间使用 <code>-</code> 分隔，不使用空格、下划线或驼峰命名。</p> <p>推荐：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">docker-installation.md </span></span><span class="line"><span class="cl">docker-image-optimization.md </span></span><span class="line"><span class="cl">mysql-deep-pagination.md </span></span></code></pre></div><p>不推荐：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">DockerInstallation.md </span></span><span class="line"><span class="cl">docker_installation.md </span></span><span class="line"><span class="cl">docker installation.md </span></span></code></pre></div><h3 id="13-文件编码">1.3 文件编码</h3> <p>Markdown 文件必须使用 UTF-8 编码。</p> <hr> <h2 id="2-标题规范">2. 标题规范</h2> <h3 id="21-文档标题">2.1 文档标题</h3> <p>按照 FEX 规范，文档标题可以使用 Setext 风格：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">Markdown 编写规范 </span></span><span class="line"><span class="cl">================ </span></span></code></pre></div><p>如果项目使用 Hugo 等现代 Markdown 工具链，也可以使用：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># Markdown 编写规范 </span></span></span></code></pre></div><p>但是，如果严格遵循 FEX Team 原规范，则推荐使用 Setext 风格作为文档标题。</p> <p>对于 Hugo 技术文章，如果 Front Matter 已经提供 <code>title</code>，正文通常不再重复一级标题。</p> <p>例如：</p>