ydoc
Version:
基于 Markdown 的静态站点生成工具
89 lines (86 loc) • 11.1 kB
HTML
<html lang="zh-CN"><head><meta charSet="UTF-8"/><meta content="text/html; charset=utf-8" http-equiv="Content-Type"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"/><meta name="apple-mobile-web-app-capable" content="yes"/><meta name="apple-mobile-web-app-status-bar-style" content="black"/><link rel="apple-touch-icon" sizes="180x180" href="../ydoc/images/apple-touch-icon.png"/><link rel="icon" type="image/png" sizes="32x32" href="../ydoc/images/favicon-32x32.png"/><link rel="icon" type="image/png" sizes="16x16" href="../ydoc/images/favicon-16x16.png"/><link rel="manifest" href="../ydoc/images/manifest.json"/><link rel="mask-icon" href="../ydoc/images/safari-pinned-tab.svg" color="#5bbad5"/><meta name="theme-color" content="#ffffff"/><meta http-equiv="Cache-Control" content="no-transform"/><meta http-equiv="Cache-Control" content="no-siteapp"/><title>文档体系-设计规范</title><link rel="stylesheet" href="../ydoc/styles/style.css"/><meta name="author" content="ymfe"/><meta name="keywords"/><meta name="description" content="ydoc description demo"/><meta id="releativePath" content=".."/><link rel="stylesheet" href="../ydoc/ydoc-plugin-search/search.css"/><link rel="stylesheet" href="../ydoc/ydoc-plugin-edit-page/editPage.css"/><link rel="stylesheet" href="../custom.css"/></head><body><div class="g-doc"><div class="m-aside"><div class="m-summary" id="js-menu"><div class="m-summary-content" id="js-menu-content"><div class="m-summary-block"><ul class="m-summary-list"><li class="item"><a href="style-guide.html" class="href">设计规范</a></li><li class="item"><div class="m-summary-block"><a href="" class="href">文档规范</a><ul class="m-summary-list indent"><li class="item"><a href="index.html#%e7%9b%ae%e5%bd%95%e7%bb%93%e6%9e%84" class="href">目录结构</a></li><li class="item"><a href="index.html#%e6%96%87%e4%bb%b6%e5%90%8d" class="href">文件名</a></li><li class="item"><a href="index.html#%e6%8e%92%e7%89%88%e6%8a%80%e5%b7%a7" class="href">排版技巧</a></li></ul></div></li></ul></div></div></div><div class="m-summary-switch" id="js-summary-switch"><svg viewBox="0 0 926.23699 573.74994" version="1.1" x="0px" y="0px" width="15" height="15" class="bottom"><g transform="translate(904.92214,-879.1482)"><path d="m -673.67664,1221.6502 -231.2455,-231.24803 55.6165,-55.627 c 30.5891,-30.59485 56.1806,-55.627 56.8701,-55.627 0.6894,0 79.8637,78.60862 175.9427,174.68583 l 174.6892,174.6858 174.6892,-174.6858 c 96.079,-96.07721 175.253196,-174.68583 175.942696,-174.68583 0.6895,0 26.281,25.03215 56.8701,55.627 l 55.6165,55.627 -231.245496,231.24803 c -127.185,127.1864-231.5279,231.248 -231.873,231.248 -0.3451,0 -104.688,-104.0616 -231.873,-231.248 z" fill="#fff"></path></g></svg><svg viewBox="0 0 926.23699 573.74994" version="1.1" x="0px" y="0px" width="15" height="15" class="top"><g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"><g id="aaa" fill="#fff" fill-rule="nonzero"><path d="M231.2455,342.502 L0,111.25397 L55.6165,55.62697 C86.2056,25.03212 111.7971,-2.99999998e-05 112.4866,-2.99999998e-05 C113.176,-2.99999998e-05 192.3503,78.60859 288.4293,174.6858 L463.1185,349.3716 L637.8077,174.6858 C733.8867,78.60859 813.060896,-2.99999997e-05 813.750396,-2.99999997e-05 C814.439896,-2.99999997e-05 840.031396,25.03212 870.620496,55.62697 L926.236996,111.25397 L694.9915,342.502 C567.8065,469.6884 463.4636,573.75 463.1185,573.75 C462.7734,573.75 358.4305,469.6884 231.2455,342.502 Z" id="Shape" transform="translate(463.118498, 286.874985) scale(1, -1) translate(-463.118498, -286.874985) "></path></g></g></svg></div></div><div class="m-main" id="js-panel"><header class="m-header" id="js-header"><div class="m-header-title js-logo"><a href="../index.html" target="_self"><img class="logo" width="36" src="../ydoc/images/dog@1x.png" srcSet="../ydoc/images/dog@2x.png 2x"/><h6 class="name">YDoc</h6></a></div><div><div class="m-search">
<div class="icon"></div>
<input type="text" class="input js-input" placeholder="搜索" />
<div class="m-search-result js-search-result"></div>
</div></div><nav class="m-header-nav js-nav"><ul class="m-header-items"><li class="item "><a class="href" href="../documents/index.html">文档</a></li><li class="item "><a class="href" href="../plugin/index.html">插件</a></li><li class="item "><a class="href" href="../theme/index.html">主题</a></li><li class="item "><a class="href" href="../examples/index.html">示例 Demo</a></li><li class="item "><span class="href">规范</span><ul class="m-header-subtitle"><li class="item"><a href="style-guide.html" class="link">设计规范</a></li><li class="item"><a href="" class="link">文档规范</a></li></ul></li></ul></nav><div id="js-nav-btn" class="m-header-btn ui-font-ydoc"></div></header><div class="m-content" id="js-content"><div id="markdown-body" class="m-content-container markdown-body"><h1>文档体系</h1>
<h2 id="目录结构">目录结构</h2>
<p>软件手册是一部完整的书，建议采用下面的目录结构。</p>
<ul>
<li><strong>简介</strong>（Introduction）： [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明</li>
<li><strong>快速上手</strong>（Getting Started）：[可选] [文件] 如何最快速地使用产品</li>
<li><strong>入门篇</strong>（Basics）： [必备] [目录] 又称”使用篇“，提供初级的使用教程
<ul>
<li><strong>环境准备</strong>（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件</li>
<li><strong>安装</strong>（Installation）：[可选] [文件] 软件的安装方法</li>
<li><strong>设置</strong>（Configuration）：[必备] [文件] 软件的设置</li>
</ul>
</li>
<li><strong>进阶篇</strong>（Advanced)：[可选] [目录] 又称”开发篇“，提供中高级的开发教程</li>
<li><strong>API</strong>（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍</li>
<li><strong>FAQ</strong>：[可选] [文件] 常见问题解答</li>
<li><strong>附录</strong>（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
<ul>
<li><strong>Glossary</strong>：[可选] [文件] 名词解释</li>
<li><strong>Recipes</strong>：[可选] [文件] 最佳实践</li>
<li><strong>Troubleshooting</strong>：[可选] [文件] 故障处理</li>
<li><strong>ChangeLog</strong>：[可选] [文件] 版本说明</li>
<li><strong>Feedback</strong>：[可选] [文件] 反馈方式</li>
</ul>
</li>
</ul>
<p>下面是两个真实范例，可参考。</p>
<ul>
<li><a href="http://redux.js.org" target="_blank">Redux 手册</a></li>
<li><a href="http://flight-manual.atom.io" target="_blank">Atom 手册</a></li>
</ul>
<h2 id="文件名">文件名</h2>
<p>文档的文件名不得含有空格。</p>
<p>文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。</p>
<pre><code>错误： 名词解释.md
正确： glossary.md
</code></pre>
<p>文件名建议只使用小写字母，不使用大写字母。</p>
<pre><code>错误：TroubleShooting.md
正确：troubleshooting.md
</code></pre>
<p>为了醒目，某些说明文件的文件名，可以使用大写字母，比如<code>README</code>、<code>LICENSE</code>。</p>
<p>文件名包含多个单词时，单词之间建议使用半角的连词线（<code>-</code>）分隔。</p>
<pre><code>不佳：advanced_usage.md
正确：advanced-usage.md
</code></pre>
<h2 id="排版技巧">排版技巧</h2>
<h4>空格的使用</h4>
<p>所有的中文字和半形的英文、数字、符号、链接之间应该插入一段间隙，这是因为挤在一起的中西文混排导致西文难以阅读，最简单的插入间隙的技巧就是使用空格，推荐使用 YDoc 插件 <a href="https://www.npmjs.com/package/ydoc-plugin-pangu" target="_blank">ydoc-plugin-pangu</a></p>
<p>查看下面的示例，会发现加入空格的段落，英文、数字、符号、链接更易读：</p>
<p>不加入空格的段落:YDoc是一个文档站构建工具,累计的Star数量已超过200个,官网链接为<a href="https://hellosean1025.github.io/ydoc/" target="_blank">YDoc官网</a>欢迎大家使用</p>
<p>加入空格的段落: YDoc 是一个文档站构建工具, 累计的 Star 数量已超过 200 个,官网链接为 <a href="https://hellosean1025.github.io/ydoc/" target="_blank">YDoc官网</a> 欢迎大家使用</p>
</div><div class="m-content-container m-paging"><div class="m-paging-prev m-paging-item"><a href="style-guide.html" class="href"><span class="ui-font-ydoc"></span>设计规范</a></div></div></div></div></div><div></div><script>
var $content = document.getElementById('js-content');
var $summaryItems = Array.prototype.slice.call(document.querySelectorAll('#js-menu .href'));
var $menu = document.getElementById('js-menu');
if (sessionStorage.prevPathname) {
sessionStorage.setItem('prevPrevPathname', sessionStorage.prevPathname);
sessionStorage.setItem('prevPrevMenuScrollTop', sessionStorage.prevMenuScrollTop);
sessionStorage.setItem('prevPrevContentScrollTop', sessionStorage.prevContentScrollTop);
}
if (sessionStorage.locationPathname) {
sessionStorage.setItem('prevPathname', sessionStorage.locationPathname);
sessionStorage.setItem('prevMenuScrollTop', sessionStorage.menuScrollTop);
sessionStorage.setItem('prevContentScrollTop', sessionStorage.contentScrollTop);
}
if ($menu && sessionStorage.menuScrollTop) {
$menu.scrollTop = sessionStorage.menuScrollTop;
}
// 刷新页面但不切换 pathname 的时候，内容区恢复到记忆的高度
if ($content && sessionStorage.contentScrollTop && window.location.pathname == sessionStorage.locationPathname) {
$content.scrollTop = sessionStorage.contentScrollTop;
} else if (sessionStorage.prevPrevPathname && sessionStorage.prevPrevPathname === window.location.pathname) {
if ($menu && sessionStorage.prevPrevMenuScrollTop) {
$menu.scrollTop = sessionStorage.prevPrevMenuScrollTop;
}
if ($content && sessionStorage.prevPrevContentScrollTop) {
$content.scrollTop = sessionStorage.prevPrevContentScrollTop;
}
}
sessionStorage.setItem('locationPathname', window.location.pathname);
</script><script src="../ydoc/scripts/plugins/dollar.min.js"></script><script src="../ydoc/scripts/plugins/responsive-nav.min.js"></script><script src="../ydoc/scripts/plugins/slideout.min.js"></script><script src="../ydoc/scripts/app.js"></script><script src="../ydoc/ydoc-plugin-search/core.js"></script><script src="../ydoc/ydoc-plugin-search/search.js"></script><script src="../ydoc/ydoc-plugin-edit-page/edit.script.js"></script><script src="../search_json.js"></script><script src="../edit_json.js"></script></body></html>