Sākums Izpētīt Palīdzība
Reģistrēties Pierakstīties
gogs
/
articles
1
0
Atdalīts 0
Faili Problēmas 0 Izmaiņu pieprasījumi 0 Vikivietne
Atzars: gh-pages
Atzari Tagi
articles
/
documentation.html

documentation.html 42 KB
Patstāvīgā saite Vēsture Neapstrādāts

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073 
  1. <!DOCTYPE html>
    2. 

  2. <html lang="en">
    3. 

  3. <head>
    4. 

  4. <meta charset="UTF-8">
    5. 

  5. <meta http-equiv="X-UA-Compatible" content="IE=edge">
    6. 

  6. <meta name="viewport" content="width=device-width, initial-scale=1.0">
    7. 

  7. <meta name="generator" content="Asciidoctor 2.0.15">
    8. 

  8. <meta name="author" content="pxzxj, pudge.zxj@gmail.com, 2021/12/12">
    9. 

  9. <title>技术文档编写指南</title>
    10. 

  10. <link rel="stylesheet" href="css/site.css">
    11. 

  11. <link href="css/custom.css" rel="stylesheet">
    12. 

  12. <script src="js/setup.js"></script><script defer src="js/site.js"></script>
    13. 

  13. 

  14. </head>
    15. 

  15. <body class="article toc2 toc-left"><div id="banner-container" class="container" role="banner">
    16. 

  16.   <div id="banner" class="contained" role="banner">
    17. 

  17.     <div id="switch-theme">
    18. 

  18.       <input type="checkbox" id="switch-theme-checkbox" />
    19. 

  19.       <label for="switch-theme-checkbox">Dark Theme</label>
    20. 

  20.     </div>
    21. 

  21.   </div>
    22. 

  22. </div>
    23. 

  23. <div id="tocbar-container" class="container" role="navigation">
    24. 

  24.   <div id="tocbar" class="contained" role="navigation">
    25. 

  25.     <button id="toggle-toc"></button>
    26. 

  26.   </div>
    27. 

  27. </div>
    28. 

  28. <div id="main-container" class="container">
    29. 

  29.   <div id="main" class="contained">
    30. 

  30.     <div id="doc" class="doc">
    31. 

  31. <div id="header">
    32. 

  32. <h1>技术文档编写指南</h1>
    33. 

  33. <div class="details">
    34. 

  34. <span id="author" class="author">pxzxj</span><br>
    35. 

  35. <span id="author2" class="author">pudge.zxj@gmail.com</span><br>
    36. 

  36. <span id="author3" class="author">2021/12/12</span><br>
    37. 

  37. </div>
    38. 

  38. <div id="toc" class="toc2">
    39. 

  39. <div id="toctitle">Table of Contents</div>
    40. 

  40. <span id="back-to-index"><a href="index.html">Back to index</a></span><ul class="sectlevel1">
    41. 

  41. <li><a href="#_introduction">1. Introduction</a></li>
    42. 

  42. <li><a href="#_docs_as_code">2. Docs as Code</a></li>
    43. 

  43. <li><a href="#_asciidoc">3. AsciiDoc</a>
    44. 

  44. <ul class="sectlevel2">
    45. 

  45. <li><a href="#_quickstart">3.1. QuickStart</a></li>
    46. 

  46. <li><a href="#_syntax">3.2. Syntax</a></li>
    47. 

  47. <li><a href="#_asciidoc_vs_markdown">3.3. AsciiDoc vs Markdown</a></li>
    48. 

  48. </ul>
    49. 

  49. </li>
    50. 

  50. <li><a href="#_asciidoctor">4. Asciidoctor</a>
    51. 

  51. <ul class="sectlevel2">
    52. 

  52. <li><a href="#_intellij_idea_plugin">4.1. Intellij IDEA Plugin</a></li>
    53. 

  53. <li><a href="#_asciidoctor_maven_plugin">4.2. Asciidoctor-Maven-Plugin</a></li>
    54. 

  54. <li><a href="#_spring_backend">4.3. Spring Backend</a>
    55. 

  55. <ul class="sectlevel3">
    56. 

  56. <li><a href="#_install">4.3.1. Install</a></li>
    57. 

  57. <li><a href="#_spring_look_and_feel">4.3.2. Spring Look and Feel</a></li>
    58. 

  58. <li><a href="#_responsive_design">4.3.3. Responsive Design</a></li>
    59. 

  59. <li><a href="#_back_to_index_link">4.3.4. "Back to Index" Link</a></li>
    60. 

  60. <li><a href="#_dark_mode">4.3.5. Dark Mode</a></li>
    61. 

  61. <li><a href="#_tabs">4.3.6. Tabs</a></li>
    62. 

  62. <li><a href="#_code_folding">4.3.7. Code Folding</a></li>
    63. 

  63. <li><a href="#_different_config_blocks">4.3.8. Different Config Blocks</a></li>
    64. 

  64. </ul>
    65. 

  65. </li>
    66. 

  66. <li><a href="#_bilibili_extension">4.4. Bilibili Extension</a></li>
    67. 

  67. </ul>
    68. 

  68. </li>
    69. 

  69. <li><a href="#_examples">5. Examples</a>
    70. 

  70. <ul class="sectlevel2">
    71. 

  71. <li><a href="#_html">5.1. Html</a></li>
    72. 

  72. <li><a href="#_pdf">5.2. Pdf</a></li>
    73. 

  73. <li><a href="#cicd">5.3. CI/CD</a></li>
    74. 

  74. <li><a href="#_doc_review">5.4. Doc Review</a></li>
    75. 

  75. </ul>
    76. 

  76. </li>
    77. 

  77. <li><a href="#_style">6. Style</a></li>
    78. 

  78. <li><a href="#_best_practice">7. Best Practice</a></li>
    79. 

  79. </ul>
    80. 

  80. </div>
    81. 

  81. </div>
    82. 

  82. <div id="content">
    83. 

  83. <div class="sect1">
    84. 

  84. <h2 id="_introduction"><a class="anchor" href="#_introduction"></a>1. Introduction</h2>
    85. 

  85. <div class="sectionbody">
    86. 

  86. <div class="paragraph">
    87. 

  87. <p>软件开发中文档跟代码同等重要，优秀的文档对软件的日常使用和后期维护都至关重要，另一方面结合国内软件厂商员工流动频繁的情况，完善文的档还能帮助新员工迅速熟悉项目及业务，
    88. 

  88. 将人员变动的影响降到最低，保证项目持续稳定运作，当然最终也能在一定程度上节约企业成本。</p>
    89. 

  89. </div>
    90. 

  90. <div class="paragraph">
    91. 

  91. <p>既然文档如此重要，那么项目组必须保证在整个项目周期中输出各类文档，包括但不限于架构设计文档、详细设计文档、代码评审记录等。
    92. 

  92. 然而大部分项目组的现状是文档缺失、管理混乱、随便写一下草草了事，其中原因当然跟需求变化快、开发周期紧、人员不足有关，
    93. 

  93. 但是文档编写工具也会极大地影响编写效率和管理方式。
    94. 

  94. 目前开发相关文档基本都是使用 <code>Word</code> 进行编写的，使用 <code>Word</code> 会存在下面几点问题：</p>
    95. 

  95. </div>
    96. 

  96. <div class="dlist">
    97. 

  97. <dl>
    98. 

  98. <dt class="hdlist1">版本管理困难 </dt>
    99. 

  99. <dd>
    100. 

  100. <p><code>Word</code> 文档是复杂格式的文档，使用版本管理软件无法方便地查看或对比每一次的修改内容。</p>
    101. 

  101. </dd>
    102. 

  102. <dt class="hdlist1">协作编写困难 </dt>
    103. 

  103. <dd>
    104. 

  104. <p>同样是因为 <code>Word</code> 文档的复杂格式，无法多人协作在一个文档上编辑，只能手动合并，合并后的文档以及无法区分特定内容的真正作者。</p>
    105. 

  105. </dd>
    106. 

  106. <dt class="hdlist1">代码支持性差 </dt>
    107. 

  107. <dd>
    108. 

  108. <p><code>Word</code> 文档主要还是用于文本内容，代码的展示效果很差，除非手工再进行复杂的格式调整。</p>
    109. 

  109. </dd>
    110. 

  110. <dt class="hdlist1">格式调整耗时 </dt>
    111. 

  111. <dd>
    112. 

  112. <p>想要获得期望的整洁美观效果，通常需要不断调整文档格式，<code>Word</code> 的格式调整等都需要鼠标操作，键鼠切换通用会降低文档编写效率，这也正是Intellij IDEA提供了如此多快捷键的原因。</p>
    113. 

  113. </dd>
    114. 

  114. <dt class="hdlist1">需要单独上传 </dt>
    115. 

  115. <dd>
    116. 

  116. <p>通常是再桌面新建一个文档，如果要上传到SVN或者Git上还需要手动复制到对应目录，很多开发文档已经写了但忘记上传。</p>
    117. 

  117. </dd>
    118. 

  118. <dt class="hdlist1">需要单独下载 </dt>
    119. 

  119. <dd>
    120. 

  120. <p>文档编写完成之后必然要供其它人查看，而要查看 <code>Word</code> 编写的文档需要专门从SVN或Git上拣出。</p>
    121. 

  121. </dd>
    122. 

  122. </dl>
    123. 

  123. </div>
    124. 

  124. </div>
    125. 

  125. </div>
    126. 

  126. <div class="sect1">
    127. 

  127. <h2 id="_docs_as_code"><a class="anchor" href="#_docs_as_code"></a>2. Docs as Code</h2>
    128. 

  128. <div class="sectionbody">
    129. 

  129. <div class="paragraph">
    130. 

  130. <p>针对上文描述的 <code>Word</code> 文档存在的诸多问题，国外的诸多企业开始基于 <code>Docs as Code</code> 的理念进行文档编写。<code>Docs as Code</code> 是指按照写代码的方式写文档，主要包括下面几点内容</p>
    131. 

  131. </div>
    132. 

  132. <div class="dlist">
    133. 

  133. <dl>
    134. 

  134. <dt class="hdlist1">使用简单文本编写文档 </dt>
    135. 

  135. <dd>
    136. 

  136. <p>这一点是最重要的要求，只有简单文本才能使用Git强大的版本管理功能。</p>
    137. 

  137. </dd>
    138. 

  138. <dt class="hdlist1">使用版本控制工具管理文档 </dt>
    139. 

  139. <dd>
    140. 

  140. <p>文档总是在不断变化的，使用SVN、Git等版本控制工具能够查看文档所有的历史记录以及作者等信息。同代码一样，文档也可以使用分支管理等功能为软件的不同版本提供不同的文档。</p>
    141. 

  141. </dd>
    142. 

  142. <dt class="hdlist1">文档评审 </dt>
    143. 

  143. <dd>
    144. 

  144. <p>代码需要评审，文档也是一样，只有评审通过的文档才能合并到主干。评审可以是线下会议的方式进行也可以是线上Review Commit或者Pull Request的方式进行。</p>
    145. 

  145. </dd>
    146. 

  146. <dt class="hdlist1">为文档编写测试 </dt>
    147. 

  147. <dd>
    148. 

  148. <p>使用测试验证文档中错别字、失效链接、代码片段等，这一点一般不做强制要求。</p>
    149. 

  149. </dd>
    150. 

  150. <dt class="hdlist1">文档自动化发布 </dt>
    151. 

  151. <dd>
    152. 

  152. <p>文档提交后能够自动发布到特定文档站点上供其它人查看。</p>
    153. 

  153. </dd>
    154. 

  154. </dl>
    155. 

  155. </div>
    156. 

  156. <div class="admonitionblock tip">
    157. 

  157. <table>
    158. 

  158. <tr>
    159. 

  159. <td class="icon">
    160. 

  160. <i class="fa icon-tip" title="Tip"></i>
    161. 

  161. </td>
    162. 

  162. <td class="content">
    163. 

  163. 更多关于 <code>Docs as Code</code> 的介绍参考 <a href="https://www.writethedocs.org/guide/docs-as-code/">writethedocs站点</a>
    164. 

  164. </td>
    165. 

  165. </tr>
    166. 

  166. </table>
    167. 

  167. </div>
    168. 

  168. </div>
    169. 

  169. </div>
    170. 

  170. <div class="sect1">
    171. 

  171. <h2 id="_asciidoc"><a class="anchor" href="#_asciidoc"></a>3. AsciiDoc</h2>
    172. 

  172. <div class="sectionbody">
    173. 

  173. <div class="paragraph">
    174. 

  174. <p><a href="https://asciidoctor.org/docs/what-is-asciidoc/">AsciiDoc</a> 是一种轻量级文本标记语言，可以用于创作笔记、文档、博客、电子书、网页、幻灯片、man手册，
    175. 

  175. 它以简单文本的方式编写可以转换为html、pdf等多种格式，部分网站如GitHub支持直接将AsciiDoc内容呈现为html。</p>
    176. 

  176. </div>
    177. 

  177. <div class="sect2">
    178. 

  178. <h3 id="_quickstart"><a class="anchor" href="#_quickstart"></a>3.1. QuickStart</h3>
    179. 

  179. <div class="listingblock">
    180. 

  180. <div class="content">
    181. 

  181. <pre>= The First Asciidoc example: Subtitle              <i class="conum" data-value="1"></i><b>(1)</b>
    182. 

  182. Lars Vogel(c) 2016 vogella GmbH                     <i class="conum" data-value="2"></i><b>(2)</b>
    183. 

  183. Version 0.3, 17.05.2021                             <i class="conum" data-value="3"></i><b>(3)</b>
    184. 

  184. :sectnums:                                          <i class="conum" data-value="4"></i><b>(4)</b>
    185. 

  185. :toc:                                               <i class="conum" data-value="5"></i><b>(5)</b>
    186. 

  186. :toclevels: 4                                       <i class="conum" data-value="6"></i><b>(6)</b>
    187. 

  187. :toc-title: My Content                              <i class="conum" data-value="7"></i><b>(7)</b>
    188. 

  188. :experimental:                                      <i class="conum" data-value="8"></i><b>(8)</b>
    189. 

  189. :description: Example AsciiDoc document             <i class="conum" data-value="9"></i><b>(9)</b>
    190. 

  190. :imagesdir: ./img                                   <i class="conum" data-value="10"></i><b>(10)</b>
    191. 

  191. 

  192. This is the optional preamble (an untitled section body). Useful for
    193. 

  193. writing simple sectionless documents consisting only of a preamble.
    194. 

  194. 

  195. == First section
    196. 

  196. 

  197. Some text
    198. 

  198. 

  199. == Second section
    200. 

  200. 

  201. More test</pre>
    202. 

  202. </div>
    203. 

  203. </div>
    204. 

  204. <div class="olist arabic">
    205. 

  205. <ol class="arabic">
    206. 

  206. <li>
    207. 

  207. <p>文档标题及副标题</p>
    208. 

  208. </li>
    209. 

  209. <li>
    210. 

  210. <p>标题下一行列出作者信息</p>
    211. 

  211. </li>
    212. 

  212. <li>
    213. 

  213. <p>文件修订版本</p>
    214. 

  214. </li>
    215. 

  215. <li>
    216. 

  216. <p>需要展示各章节编号</p>
    217. 

  217. </li>
    218. 

  218. <li>
    219. 

  219. <p>生出文档目录，toc即Table Of Contents</p>
    220. 

  220. </li>
    221. 

  221. <li>
    222. 

  222. <p>默认toc仅展示两级目录，toclevel可以修改为其它值</p>
    223. 

  223. </li>
    224. 

  224. <li>
    225. 

  225. <p>默认目录标题为 <code>Table Of Contents</code>，使用toc-title修改为其它值</p>
    226. 

  226. </li>
    227. 

  227. <li>
    228. 

  228. <p>启用实验性功能</p>
    229. 

  229. </li>
    230. 

  230. <li>
    231. 

  231. <p>文档的描述</p>
    232. 

  232. </li>
    233. 

  233. <li>
    234. 

  234. <p>默认图片目录</p>
    235. 

  235. </li>
    236. 

  236. </ol>
    237. 

  237. </div>
    238. 

  238. </div>
    239. 

  239. <div class="sect2">
    240. 

  240. <h3 id="_syntax"><a class="anchor" href="#_syntax"></a>3.2. Syntax</h3>
    241. 

  241. <div class="paragraph">
    242. 

  242. <p>AsciiDoc相关语法参考 <a href="https://docs.asciidoctor.org/asciidoc/latest/">官方站点</a></p>
    243. 

  243. </div>
    244. 

  244. </div>
    245. 

  245. <div class="sect2">
    246. 

  246. <h3 id="_asciidoc_vs_markdown"><a class="anchor" href="#_asciidoc_vs_markdown"></a>3.3. AsciiDoc vs Markdown</h3>
    247. 

  247. <div class="admonitionblock tip">
    248. 

  248. <table>
    249. 

  249. <tr>
    250. 

  250. <td class="icon">
    251. 

  251. <i class="fa icon-tip" title="Tip"></i>
    252. 

  252. </td>
    253. 

  253. <td class="content">
    254. 

  254. <a href="https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/">官方站点</a>详细对比了AsciiDoc和Markdown，本节内容主要是对其进行摘取和翻译
    255. 

  255. </td>
    256. 

  256. </tr>
    257. 

  257. </table>
    258. 

  258. </div>
    259. 

  259. <div class="paragraph">
    260. 

  260. <p>Markdown是最流行的轻量级文本标记语言，它的语法简单易于学习，很多开源项目的文档也都是使用Markdown编写的包括Dubbo、Nacos等，
    261. 

  261. 然而语法简单也注定它无法满足一些复杂常见的文档编写需求包括表格、文档交叉引用、脚注、嵌入视频等。而AsciiDoc既保留了简洁的编写语法，
    262. 

  262. 又考虑到了几乎所有场景的文档编写需求，很多技术书籍就是使用AsciiDoc编写完成后打印出版的。最重要的是AsciiDoc的语法设计为可扩展的，
    263. 

  263. 用户完全可以根据自己的需求设计特殊AsciiDoc语法。</p>
    264. 

  264. </div>
    265. 

  265. <div class="paragraph">
    266. 

  266. <p>下表对AsciiDoc语法和Markdown语法的比较，不过此处仅关注了AsciiDoc和Markdown都支持的语法</p>
    267. 

  267. </div>
    268. 

  268. <table class="tableblock frame-all grid-all fit-content">
    269. 

  269. <colgroup>
    270. 

  270. <col>
    271. 

  271. <col>
    272. 

  272. <col>
    273. 

  273. </colgroup>
    274. 

  274. <thead>
    275. 

  275. <tr>
    276. 

  276. <th class="tableblock halign-left valign-top">Language Feature</th>
    277. 

  277. <th class="tableblock halign-left valign-top">Markdown</th>
    278. 

  278. <th class="tableblock halign-left valign-top">AsciiDoc</th>
    279. 

  279. </tr>
    280. 

  280. </thead>
    281. 

  281. <tbody>
    282. 

  282. <tr>
    283. 

  283. <td class="tableblock halign-left valign-top"><p class="tableblock">加粗(受约束)</p></td>
    284. 

  284. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    285. 

  285. <div class="content">
    286. 

  286. <pre class="highlight"><code class="language-markdown" data-lang="markdown">**bold**</code></pre>
    287. 

  287. </div>
    288. 

  288. </div></div></td>
    289. 

  289. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    290. 

  290. <div class="content">
    291. 

  291. <pre class="highlight"><code>*bold*</code></pre>
    292. 

  292. </div>
    293. 

  293. </div></div></td>
    294. 

  294. </tr>
    295. 

  295. <tr>
    296. 

  296. <td class="tableblock halign-left valign-top"><p class="tableblock">加粗 (不受约束)</p></td>
    297. 

  297. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    298. 

  298. <div class="content">
    299. 

  299. <pre class="highlight"><code class="language-markdown" data-lang="markdown">**b**old</code></pre>
    300. 

  300. </div>
    301. 

  301. </div></div></td>
    302. 

  302. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    303. 

  303. <div class="content">
    304. 

  304. <pre class="highlight"><code>**b**old</code></pre>
    305. 

  305. </div>
    306. 

  306. </div></div></td>
    307. 

  307. </tr>
    308. 

  308. <tr>
    309. 

  309. <td class="tableblock halign-left valign-top"><p class="tableblock">斜体 (受约束)</p></td>
    310. 

  310. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    311. 

  311. <div class="content">
    312. 

  312. <pre class="highlight"><code class="language-markdown" data-lang="markdown">*italic*</code></pre>
    313. 

  313. </div>
    314. 

  314. </div></div></td>
    315. 

  315. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    316. 

  316. <div class="content">
    317. 

  317. <pre class="highlight"><code>_italic_</code></pre>
    318. 

  318. </div>
    319. 

  319. </div></div></td>
    320. 

  320. </tr>
    321. 

  321. <tr>
    322. 

  322. <td class="tableblock halign-left valign-top"><p class="tableblock">斜体 (不受约束)</p></td>
    323. 

  323. <td class="tableblock halign-left valign-top"><p class="tableblock"><em>n/a</em></p></td>
    324. 

  324. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    325. 

  325. <div class="content">
    326. 

  326. <pre class="highlight"><code>__i__talic</code></pre>
    327. 

  327. </div>
    328. 

  328. </div></div></td>
    329. 

  329. </tr>
    330. 

  330. <tr>
    331. 

  331. <td class="tableblock halign-left valign-top"><p class="tableblock">等宽词 (受约束)</p></td>
    332. 

  332. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    333. 

  333. <div class="content">
    334. 

  334. <pre class="highlight"><code class="language-markdown" data-lang="markdown">`monospace`</code></pre>
    335. 

  335. </div>
    336. 

  336. </div></div></td>
    337. 

  337. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    338. 

  338. <div class="content">
    339. 

  339. <pre class="highlight"><code>`monospace`</code></pre>
    340. 

  340. </div>
    341. 

  341. </div></div></td>
    342. 

  342. </tr>
    343. 

  343. <tr>
    344. 

  344. <td class="tableblock halign-left valign-top"><p class="tableblock">等宽词 (不受约束)</p></td>
    345. 

  345. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    346. 

  346. <div class="content">
    347. 

  347. <pre class="highlight"><code class="language-markdown" data-lang="markdown">`m`onospace</code></pre>
    348. 

  348. </div>
    349. 

  349. </div></div></td>
    350. 

  350. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    351. 

  351. <div class="content">
    352. 

  352. <pre class="highlight"><code>``m``onospace</code></pre>
    353. 

  353. </div>
    354. 

  354. </div></div></td>
    355. 

  355. </tr>
    356. 

  356. <tr>
    357. 

  357. <td class="tableblock halign-left valign-top"><p class="tableblock">超链接</p></td>
    358. 

  358. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    359. 

  359. <div class="content">
    360. 

  360. <pre class="highlight"><code class="language-markdown" data-lang="markdown">[Asciidoctor](https://asciidoctor.org)</code></pre>
    361. 

  361. </div>
    362. 

  362. </div></div></td>
    363. 

  363. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    364. 

  364. <div class="content">
    365. 

  365. <pre class="highlight"><code>https://asciidoctor.org[Asciidoctor]</code></pre>
    366. 

  366. </div>
    367. 

  367. </div></div></td>
    368. 

  368. </tr>
    369. 

  369. <tr>
    370. 

  370. <td class="tableblock halign-left valign-top"><p class="tableblock">相对路径链接</p></td>
    371. 

  371. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    372. 

  372. <div class="content">
    373. 

  373. <pre class="highlight"><code class="language-markdown" data-lang="markdown">[user guide](user-guide.html)</code></pre>
    374. 

  374. </div>
    375. 

  375. </div></div></td>
    376. 

  376. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    377. 

  377. <div class="content">
    378. 

  378. <pre class="highlight"><code>link:user-guide.html[user guide]
    379. 

  379. xref:user-guide.adoc[user guide]</code></pre>
    380. 

  380. </div>
    381. 

  381. </div></div></td>
    382. 

  382. </tr>
    383. 

  383. <tr>
    384. 

  384. <td class="tableblock halign-left valign-top"><p class="tableblock">文件链接</p></td>
    385. 

  385. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    386. 

  386. <div class="content">
    387. 

  387. <pre class="highlight"><code class="language-markdown" data-lang="markdown">[get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf)</code></pre>
    388. 

  388. </div>
    389. 

  389. </div></div></td>
    390. 

  390. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    391. 

  391. <div class="content">
    392. 

  392. <pre class="highlight"><code>link:{site-url}/assets/mydoc.pdf[get the PDF]</code></pre>
    393. 

  393. </div>
    394. 

  394. </div></div></td>
    395. 

  395. </tr>
    396. 

  396. <tr>
    397. 

  397. <td class="tableblock halign-left valign-top"><p class="tableblock">交叉引用</p></td>
    398. 

  398. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    399. 

  399. <div class="content">
    400. 

  400. <pre class="highlight"><code class="language-markdown" data-lang="markdown">See [Usage](#_usage).
    401. 

  401. 

  402. &lt;h2 id="_usage"&gt;Usage&lt;/h2&gt;</code></pre>
    403. 

  403. </div>
    404. 

  404. </div></div></td>
    405. 

  405. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    406. 

  406. <div class="content">
    407. 

  407. <pre class="highlight"><code>See &lt;&lt;_usage&gt;&gt;.
    408. 

  408. 

  409. == Usage</code></pre>
    410. 

  410. </div>
    411. 

  411. </div></div></td>
    412. 

  412. </tr>
    413. 

  413. <tr>
    414. 

  414. <td class="tableblock halign-left valign-top"><p class="tableblock">锚点</p></td>
    415. 

  415. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    416. 

  416. <div class="content">
    417. 

  417. <pre class="highlight"><code class="language-markdown" data-lang="markdown">&lt;h2 id="usage"&gt;Usage&lt;/h2&gt;</code></pre>
    418. 

  418. </div>
    419. 

  419. </div></div></td>
    420. 

  420. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    421. 

  421. <div class="content">
    422. 

  422. <pre class="highlight"><code>[#usage]
    423. 

  423. == Usage</code></pre>
    424. 

  424. </div>
    425. 

  425. </div></div></td>
    426. 

  426. </tr>
    427. 

  427. <tr>
    428. 

  428. <td class="tableblock halign-left valign-top"><p class="tableblock">内联图片</p></td>
    429. 

  429. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    430. 

  430. <div class="content">
    431. 

  431. <pre class="highlight"><code class="language-markdown" data-lang="markdown">![Logo](/images/logo.png)</code></pre>
    432. 

  432. </div>
    433. 

  433. </div></div></td>
    434. 

  434. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    435. 

  435. <div class="content">
    436. 

  436. <pre class="highlight"><code>image:logo.png[Logo]</code></pre>
    437. 

  437. </div>
    438. 

  438. </div></div></td>
    439. 

  439. </tr>
    440. 

  440. <tr>
    441. 

  441. <td class="tableblock halign-left valign-top"><p class="tableblock">图片</p></td>
    442. 

  442. <td class="tableblock halign-left valign-top"><p class="tableblock"><em>n/a</em></p></td>
    443. 

  443. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    444. 

  444. <div class="content">
    445. 

  445. <pre class="highlight"><code>image::logo.png[Logo]</code></pre>
    446. 

  446. </div>
    447. 

  447. </div></div></td>
    448. 

  448. </tr>
    449. 

  449. <tr>
    450. 

  450. <td class="tableblock halign-left valign-top"><p class="tableblock">章节标题</p></td>
    451. 

  451. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    452. 

  452. <div class="content">
    453. 

  453. <pre class="highlight"><code class="language-markdown" data-lang="markdown">## Heading 2</code></pre>
    454. 

  454. </div>
    455. 

  455. </div></div></td>
    456. 

  456. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    457. 

  457. <div class="content">
    458. 

  458. <pre class="highlight"><code>== Heading 2</code></pre>
    459. 

  459. </div>
    460. 

  460. </div></div></td>
    461. 

  461. </tr>
    462. 

  462. <tr>
    463. 

  463. <td class="tableblock halign-left valign-top"><p class="tableblock">引用</p></td>
    464. 

  464. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    465. 

  465. <div class="content">
    466. 

  466. <pre class="highlight"><code class="language-markdown" data-lang="markdown">&gt; Quoted text.
    467. 

  467. &gt;
    468. 

  468. &gt; Another paragraph in quote.</code></pre>
    469. 

  469. </div>
    470. 

  470. </div></div></td>
    471. 

  471. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    472. 

  472. <div class="content">
    473. 

  473. <pre class="highlight"><code>____
    474. 

  474. Quoted text.
    475. 

  475. 

  476. Another paragraph in quote.
    477. 

  477. ____</code></pre>
    478. 

  478. </div>
    479. 

  479. </div></div></td>
    480. 

  480. </tr>
    481. 

  481. <tr>
    482. 

  482. <td class="tableblock halign-left valign-top"><p class="tableblock">文本</p></td>
    483. 

  483. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    484. 

  484. <div class="content">
    485. 

  485. <pre class="highlight"><code class="language-markdown" data-lang="markdown">    $ gem install asciidoctor</code></pre>
    486. 

  486. </div>
    487. 

  487. </div></div></td>
    488. 

  488. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    489. 

  489. <div class="title">Indented (by 1 or more spaces)</div>
    490. 

  490. <div class="content">
    491. 

  491. <pre class="highlight"><code> $ gem install asciidoctor</code></pre>
    492. 

  492. </div>
    493. 

  493. </div>
    494. 

  494. <div class="listingblock">
    495. 

  495. <div class="title">Delimited</div>
    496. 

  496. <div class="content">
    497. 

  497. <pre class="highlight"><code>....
    498. 

  498. $ gem install asciidoctor
    499. 

  499. ....</code></pre>
    500. 

  500. </div>
    501. 

  501. </div></div></td>
    502. 

  502. </tr>
    503. 

  503. <tr>
    504. 

  504. <td class="tableblock halign-left valign-top"><p class="tableblock">代码</p></td>
    505. 

  505. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    506. 

  506. <div class="content">
    507. 

  507. <pre class="highlight"><code class="language-markdown" data-lang="markdown">```java
    508. 

  508. public class Person {
    509. 

  509.   private String name;
    510. 

  510.   public Person(String name) {
    511. 

  511.     this.name = name;
    512. 

  512.   }
    513. 

  513. }
    514. 

  514. ```</code></pre>
    515. 

  515. </div>
    516. 

  516. </div></div></td>
    517. 

  517. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    518. 

  518. <div class="content">
    519. 

  519. <pre class="highlight"><code>[source,java]
    520. 

  520. ----
    521. 

  521. public class Person {
    522. 

  522.   private String name;
    523. 

  523.   public Person(String name) {
    524. 

  524.     this.name = name;
    525. 

  525.   }
    526. 

  526. }
    527. 

  527. ----</code></pre>
    528. 

  528. </div>
    529. 

  529. </div></div></td>
    530. 

  530. </tr>
    531. 

  531. <tr>
    532. 

  532. <td class="tableblock halign-left valign-top"><p class="tableblock">无序列表</p></td>
    533. 

  533. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    534. 

  534. <div class="content">
    535. 

  535. <pre class="highlight"><code class="language-markdown" data-lang="markdown">* apples
    536. 

  536. * orange
    537. 

  537.   * temple
    538. 

  538.   * navel
    539. 

  539. * bananas</code></pre>
    540. 

  540. </div>
    541. 

  541. </div></div></td>
    542. 

  542. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    543. 

  543. <div class="content">
    544. 

  544. <pre class="highlight"><code>* apples
    545. 

  545. * oranges
    546. 

  546. ** temple
    547. 

  547. ** navel
    548. 

  548. * bananas</code></pre>
    549. 

  549. </div>
    550. 

  550. </div></div></td>
    551. 

  551. </tr>
    552. 

  552. <tr>
    553. 

  553. <td class="tableblock halign-left valign-top"><p class="tableblock">有序列表</p></td>
    554. 

  554. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    555. 

  555. <div class="content">
    556. 

  556. <pre class="highlight"><code class="language-markdown" data-lang="markdown">1. first
    557. 

  557. 2. second
    558. 

  558. 3. third</code></pre>
    559. 

  559. </div>
    560. 

  560. </div></div></td>
    561. 

  561. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    562. 

  562. <div class="content">
    563. 

  563. <pre class="highlight"><code>. first
    564. 

  564. . second
    565. 

  565. . third</code></pre>
    566. 

  566. </div>
    567. 

  567. </div></div></td>
    568. 

  568. </tr>
    569. 

  569. <tr>
    570. 

  570. <td class="tableblock halign-left valign-top"><p class="tableblock">文档头</p></td>
    571. 

  571. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    572. 

  572. <div class="title">Slapped on as &#8220;front matter&#8221;</div>
    573. 

  573. <div class="content">
    574. 

  574. <pre class="highlight"><code class="language-markdown" data-lang="markdown">---
    575. 

  575. layout: docs
    576. 

  576. title: Writing posts
    577. 

  577. prev_section: defining-frontmatter
    578. 

  578. next_section: creating-pages
    579. 

  579. permalink: /docs/writing-posts/
    580. 

  580. ---</code></pre>
    581. 

  581. </div>
    582. 

  582. </div></div></td>
    583. 

  583. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    584. 

  584. <div class="title">Native support!</div>
    585. 

  585. <div class="content">
    586. 

  586. <pre class="highlight"><code>= Writing posts
    587. 

  587. :page-layout: base
    588. 

  588. :showtitle:
    589. 

  589. :prev_section: defining-frontmatter
    590. 

  590. :next_section: creating-pages</code></pre>
    591. 

  591. </div>
    592. 

  592. </div></div></td>
    593. 

  593. </tr>
    594. 

  594. <tr>
    595. 

  595. <td class="tableblock halign-left valign-top"><p class="tableblock">警告</p></td>
    596. 

  596. <td class="tableblock halign-left valign-top"><p class="tableblock"><em>n/a</em></p></td>
    597. 

  597. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    598. 

  598. <div class="content">
    599. 

  599. <pre class="highlight"><code>TIP: You can add line numbers to source listings by adding the word `numbered` in the attribute list after the language name.</code></pre>
    600. 

  600. </div>
    601. 

  601. </div></div></td>
    602. 

  602. </tr>
    603. 

  603. <tr>
    604. 

  604. <td class="tableblock halign-left valign-top"><p class="tableblock">块标题</p></td>
    605. 

  605. <td class="tableblock halign-left valign-top"><p class="tableblock"><em>n/a</em></p></td>
    606. 

  606. <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
    607. 

  607. <div class="content">
    608. 

  608. <pre class="highlight"><code>.Grocery list
    609. 

  609. * Milk
    610. 

  610. * Eggs
    611. 

  611. * Bread</code></pre>
    612. 

  612. </div>
    613. 

  613. </div></div></td>
    614. 

  614. </tr>
    615. 

  615. </tbody>
    616. 

  616. </table>
    617. 

  617. <div class="admonitionblock note">
    618. 

  618. <table>
    619. 

  619. <tr>
    620. 

  620. <td class="icon">
    621. 

  621. <i class="fa icon-note" title="Note"></i>
    622. 

  622. </td>
    623. 

  623. <td class="content">
    624. 

  624. 受约束的是指使用时前后必须有空格，不受约束的则表示可以在任何地方使用
    625. 

  625. </td>
    626. 

  626. </tr>
    627. 

  627. </table>
    628. 

  628. </div>
    629. 

  629. </div>
    630. 

  630. </div>
    631. 

  631. </div>
    632. 

  632. <div class="sect1">
    633. 

  633. <h2 id="_asciidoctor"><a class="anchor" href="#_asciidoctor"></a>4. Asciidoctor</h2>
    634. 

  634. <div class="sectionbody">
    635. 

  635. <div class="paragraph">
    636. 

  636. <p><a href="https://asciidoctor.org/">Asciidoctor</a> 是最流行的AsciiDoc处理软件，它使用Ruby编写，源码托管在GitHub上，
    637. 

  637. 很多知名的项目如Spring、Hibernate、JUnit等都是使用Asciidoctor生成项目文档的。</p>
    638. 

  638. </div>
    639. 

  639. <div class="paragraph">
    640. 

  640. <p>AsciiDoctor能够快速将asciidoc文档转换为Html5、Docbook、Pdf、Epub3等多种格式。
    641. 

  641. 同时AsciiDoctor还提供了很多扩展接口，允许开发者根据特定需求扩展AsciiDoctor的功能，
    642. 

  642. 下文介绍的 <code>Bilibili Extension</code> 以及 <code>Spring Backend</code> 就是对AsciiDoctor的扩展。</p>
    643. 

  643. </div>
    644. 

  644. <div class="paragraph">
    645. 

  645. <p>Asciidoctor包含了多种不同形式的实现用于满足不同人员的需求，包括命令行工具、Intellij IDEA插件、浏览器插件、Maven插件、Gradle插件等，
    646. 

  646. 本文选择对Java开发者比较友好的Intellij IDEA和maven插件进行介绍。</p>
    647. 

  647. </div>
    648. 

  648. <div class="sect2">
    649. 

  649. <h3 id="_intellij_idea_plugin"><a class="anchor" href="#_intellij_idea_plugin"></a>4.1. Intellij IDEA Plugin</h3>
    650. 

  650. <div class="paragraph">
    651. 

  651. <p>搜索AsciiDoc插件安装即可。</p>
    652. 

  652. </div>
    653. 

  653. <div class="imageblock">
    654. 

  654. <div class="content">
    655. 

  655. <img src="images/install-from-marketplace.png" alt="install from marketplace">
    656. 

  656. </div>
    657. 

  657. </div>
    658. 

  658. <div class="paragraph">
    659. 

  659. <p>插件安装完成后新建.adoc结尾的文件就会自动使用此插件，左侧为使用asciidoc编写的原始内容，右侧为渲染后的效果。</p>
    660. 

  660. </div>
    661. 

  661. <div class="imageblock">
    662. 

  662. <div class="content">
    663. 

  663. <img src="images/asciidoc-intellij-idea-plugin-editor.png" alt="asciidoc intellij idea plugin editor">
    664. 

  664. </div>
    665. 

  665. </div>
    666. 

  666. </div>
    667. 

  667. <div class="sect2">
    668. 

  668. <h3 id="_asciidoctor_maven_plugin"><a class="anchor" href="#_asciidoctor_maven_plugin"></a>4.2. Asciidoctor-Maven-Plugin</h3>
    669. 

  669. <div class="paragraph">
    670. 

  670. <p>Asciidoctor Maven Plugin可以将AsciiDoc文档转换为多种格式。跟其它Maven插件一样，在 <code>pom.xml</code> 中添加AsciiDoctor插件配置即可开始使用。</p>
    671. 

  671. </div>
    672. 

  672. <div class="listingblock">
    673. 

  673. <div class="content">
    674. 

  674. <pre class="highlight"><code class="language-xml" data-lang="xml">&lt;project&gt;
    675. 

  675.     ...
    676. 

  676.     &lt;build&gt;
    677. 

  677.         ...
    678. 

  678.         &lt;plugin&gt;
    679. 

  679.             &lt;groupId&gt;org.asciidoctor&lt;/groupId&gt;
    680. 

  680.             &lt;artifactId&gt;asciidoctor-maven-plugin&lt;/artifactId&gt;
    681. 

  681.             &lt;version&gt;2.2.1&lt;/version&gt;
    682. 

  682.             &lt;executions&gt;
    683. 

  683.                 &lt;execution&gt;
    684. 

  684.                     &lt;id&gt;convert-to-html&lt;/id&gt;
    685. 

  685.                     &lt;phase&gt;generate-resources&lt;/phase&gt;          <i class="conum" data-value="1"></i><b>(1)</b>
    686. 

  686.                     &lt;goals&gt;
    687. 

  687.                         &lt;goal&gt;process-asciidoc&lt;/goal&gt;
    688. 

  688.                     &lt;/goals&gt;
    689. 

  689.                     &lt;configuration&gt;
    690. 

  690.                         &lt;outputDirectory&gt;${project.build.directory}/html&lt;/outputDirectory&gt;       <i class="conum" data-value="2"></i><b>(2)</b>
    691. 

  691.                         &lt;attributes&gt;                           <i class="conum" data-value="3"></i><b>(3)</b>
    692. 

  692.                             &lt;source-highlighter&gt;coderay&lt;/source-highlighter&gt;
    693. 

  693.                             &lt;imagesdir&gt;./images&lt;/imagesdir&gt;
    694. 

  694.                             &lt;toc&gt;left&lt;/toc&gt;
    695. 

  695.                             &lt;icons&gt;font&lt;/icons&gt;
    696. 

  696.                         &lt;/attributes&gt;
    697. 

  697.                     &lt;/configuration&gt;
    698. 

  698.                 &lt;/execution&gt;
    699. 

  699.             &lt;/executions&gt;
    700. 

  700.         &lt;/plugin&gt;
    701. 

  701.   ...
    702. 

  702. &lt;/project&gt;</code></pre>
    703. 

  703. </div>
    704. 

  704. </div>
    705. 

  705. <div class="olist arabic">
    706. 

  706. <ol class="arabic">
    707. 

  707. <li>
    708. 

  708. <p>配置插件执行阶段和目标</p>
    709. 

  709. </li>
    710. 

  710. <li>
    711. 

  711. <p><code>Configuration</code> 中配置插件相关参数</p>
    712. 

  712. </li>
    713. 

  713. <li>
    714. 

  714. <p>文档属性</p>
    715. 

  715. </li>
    716. 

  716. </ol>
    717. 

  717. </div>
    718. 

  718. <div class="paragraph">
    719. 

  719. <p><code>Configuration</code> 中支持众多参数的配置，下面选择几个重要的进行说明，完整参数列表参考 <a href="https://docs.asciidoctor.org/maven-tools/latest/plugin/goals/process-asciidoc/">官方文档</a></p>
    720. 

  720. </div>
    721. 

  721. <div class="dlist">
    722. 

  722. <dl>
    723. 

  723. <dt class="hdlist1"><em><strong>sourceDirectory</strong></em> </dt>
    724. 

  724. <dd>
    725. 

  725. <p>源文件目录，默认检查 <em>/src/docs/asciidoc, /src/asciidoc和/src/main/asciidoc</em>。</p>
    726. 

  726. </dd>
    727. 

  727. <dt class="hdlist1"><em><strong>sourceDocumentName</strong></em> </dt>
    728. 

  728. <dd>
    729. 

  729. <p>源文件名称，默认检查 <code>sourceDirectory</code> 下的所有文件。</p>
    730. 

  730. </dd>
    731. 

  731. <dt class="hdlist1"><em><strong>sourceDocumentExtensions</strong></em> </dt>
    732. 

  732. <dd>
    733. 

  733. <p>源文件扩展名，默认包含<em>ad, adoc, and asciidoc</em>。</p>
    734. 

  734. </dd>
    735. 

  735. <dt class="hdlist1"><em><strong>outputDirectory</strong></em> </dt>
    736. 

  736. <dd>
    737. 

  737. <p>转换后文件输出目录，默认为<em>${project.build.directory}/generated-docs.</em>。</p>
    738. 

  738. </dd>
    739. 

  739. <dt class="hdlist1"><em><strong>backend</strong></em> </dt>
    740. 

  740. <dd>
    741. 

  741. <p>转换目标类型，默认是html5。</p>
    742. 

  742. </dd>
    743. 

  743. <dt class="hdlist1"><em><strong>doctype</strong></em> </dt>
    744. 

  744. <dd>
    745. 

  745. <p>支持book和article，默认使用article。</p>
    746. 

  746. </dd>
    747. 

  747. </dl>
    748. 

  748. </div>
    749. 

  749. </div>
    750. 

  750. <div class="sect2">
    751. 

  751. <h3 id="_spring_backend"><a class="anchor" href="#_spring_backend"></a>4.3. Spring Backend</h3>
    752. 

  752. <div class="paragraph">
    753. 

  753. <p>Asciidoctor提供了通用的文档输出格式，而不同框架或软件则可以根据自身需求进行扩展，Spring为了提升文档可读性创建了 <a href="https://github.com/spring-io/spring-asciidoctor-backends">spring-asciidoctor-backends</a>项目用于生成Spring风格的html文档。</p>
    754. 

  754. </div>
    755. 

  755. <div class="sect3">
    756. 

  756. <h4 id="_install"><a class="anchor" href="#_install"></a>4.3.1. Install</h4>
    757. 

  757. <div class="paragraph">
    758. 

  758. <p>再Asciidoctor Maven插件中添加Spring Backend相关配置即可使用。</p>
    759. 

  759. </div>
    760. 

  760. <div class="listingblock">
    761. 

  761. <div class="content">
    762. 

  762. <pre class="highlight"><code class="language-xml" data-lang="xml">&lt;plugin&gt;
    763. 

  763. 	&lt;groupId&gt;org.asciidoctor&lt;/groupId&gt;
    764. 

  764. 	&lt;artifactId&gt;asciidoctor-maven-plugin&lt;/artifactId&gt;
    765. 

  765. 	&lt;version&gt;2.1.0&lt;/version&gt;
    766. 

  766. 	&lt;executions&gt;
    767. 

  767. 		&lt;execution&gt;
    768. 

  768. 			&lt;id&gt;generate-html-documentation&lt;/id&gt;
    769. 

  769. 			&lt;phase&gt;prepare-package&lt;/phase&gt;
    770. 

  770. 			&lt;goals&gt;
    771. 

  771. 				&lt;goal&gt;process-asciidoc&lt;/goal&gt;
    772. 

  772. 			&lt;/goals&gt;
    773. 

  773. 			&lt;configuration&gt;
    774. 

  774. 				&lt;backend&gt;spring-html&lt;/backend&gt;                      <i class="conum" data-value="1"></i><b>(1)</b>
    775. 

  775. 			&lt;/configuration&gt;
    776. 

  776. 		&lt;/execution&gt;
    777. 

  777. 	&lt;/executions&gt;
    778. 

  778. 	&lt;dependencies&gt;
    779. 

  779. 		&lt;dependency&gt;                                                <i class="conum" data-value="2"></i><b>(2)</b>
    780. 

  780. 			&lt;groupId&gt;io.spring.asciidoctor.backends&lt;/groupId&gt;
    781. 

  781. 			&lt;artifactId&gt;spring-asciidoctor-backends&lt;/artifactId&gt;
    782. 

  782. 			&lt;version&gt;${spring-asciidoctor-backends.version}&lt;/version&gt;
    783. 

  783. 		&lt;/dependency&gt;
    784. 

  784. 	&lt;/dependencies&gt;
    785. 

  785. &lt;/plugin&gt;
    786. 

  786. 

  787. &lt;repositories&gt;
    788. 

  788. 	&lt;repository&gt;                                                    <i class="conum" data-value="3"></i><b>(3)</b>
    789. 

  789. 		&lt;id&gt;spring-release&lt;/id&gt;
    790. 

  790. 		&lt;name&gt;Spring Releases&lt;/name&gt;
    791. 

  791. 		&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
    792. 

  792. 		&lt;snapshots&gt;
    793. 

  793. 			&lt;enabled&gt;false&lt;/enabled&gt;
    794. 

  794. 		&lt;/snapshots&gt;
    795. 

  795. 	&lt;/repository&gt;
    796. 

  796. &lt;/repositories&gt;</code></pre>
    797. 

  797. </div>
    798. 

  798. </div>
    799. 

  799. <div class="olist arabic">
    800. 

  800. <ol class="arabic">
    801. 

  801. <li>
    802. 

  802. <p>backend设置为spring-html</p>
    803. 

  803. </li>
    804. 

  804. <li>
    805. 

  805. <p>添加spring-backend依赖</p>
    806. 

  806. </li>
    807. 

  807. <li>
    808. 

  808. <p>配置Spring Maven仓库</p>
    809. 

  809. </li>
    810. 

  810. </ol>
    811. 

  811. </div>
    812. 

  812. </div>
    813. 

  813. <div class="sect3">
    814. 

  814. <h4 id="_spring_look_and_feel"><a class="anchor" href="#_spring_look_and_feel"></a>4.3.2. Spring Look and Feel</h4>
    815. 

  815. <div class="paragraph">
    816. 

  816. <p>生成的html样式与Spring官网保持一致，左上角展示Spring的Logo。</p>
    817. 

  817. </div>
    818. 

  818. <div class="admonitionblock tip">
    819. 

  819. <table>
    820. 

  820. <tr>
    821. 

  821. <td class="icon">
    822. 

  822. <i class="fa icon-tip" title="Tip"></i>
    823. 

  823. </td>
    824. 

  824. <td class="content">
    825. 

  825. 后期可能会允许使用自定义的Logo，参考 <a href="https://github.com/spring-io/spring-asciidoctor-backends/issues/24">Ability to override the banner logo</a>
    826. 

  826. </td>
    827. 

  827. </tr>
    828. 

  828. </table>
    829. 

  829. </div>
    830. 

  830. </div>
    831. 

  831. <div class="sect3">
    832. 

  832. <h4 id="_responsive_design"><a class="anchor" href="#_responsive_design"></a>4.3.3. Responsive Design</h4>
    833. 

  833. <div class="paragraph">
    834. 

  834. <p>生成的html遵循响应式设计，能在各种设备上很好地展示，如台式机、平板电脑、智能手机等。</p>
    835. 

  835. </div>
    836. 

  836. </div>
    837. 

  837. <div class="sect3">
    838. 

  838. <h4 id="_back_to_index_link"><a class="anchor" href="#_back_to_index_link"></a>4.3.4. "Back to Index" Link</h4>
    839. 

  839. <div class="paragraph">
    840. 

  840. <p>如果当前页面部署index.html,那么提供一个Back to Index链接用于返回到首页</p>
    841. 

  841. </div>
    842. 

  842. </div>
    843. 

  843. <div class="sect3">
    844. 

  844. <h4 id="_dark_mode"><a class="anchor" href="#_dark_mode"></a>4.3.5. Dark Mode</h4>
    845. 

  845. <div class="paragraph">
    846. 

  846. <p>页面右上角支持切换黑夜模式，模式设置保存在本地，无需每次重新加载后设置</p>
    847. 

  847. </div>
    848. 

  848. </div>
    849. 

  849. <div class="sect3">
    850. 

  850. <h4 id="_tabs"><a class="anchor" href="#_tabs"></a>4.3.6. Tabs</h4>
    851. 

  851. <div class="paragraph">
    852. 

  852. <p>支持多个Tab页合并与切换，常见的如Maven和Gradle，Java和Groovy、Kotlin</p>
    853. 

  853. </div>
    854. 

  854. <div class="listingblock primary">
    855. 

  855. <div class="title">Maven</div>
    856. 

  856. <div class="content">
    857. 

  857. <pre class="highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
    858. 

  858.     &lt;groupId&gt;com.example&lt;/groupId&gt;
    859. 

  859.     &lt;artifactId&gt;some-library&lt;/artifactId&gt;
    860. 

  860.     &lt;version&gt;1.2.3&lt;/version&gt;
    861. 

  861. &lt;/dependency&gt;</code></pre>
    862. 

  862. </div>
    863. 

  863. </div>
    864. 

  864. <div class="listingblock secondary">
    865. 

  865. <div class="title">Gradle</div>
    866. 

  866. <div class="content">
    867. 

  867. <pre class="highlight"><code>compile 'com.example:some-library:1.2.3'</code></pre>
    868. 

  868. </div>
    869. 

  869. </div>
    870. 

  870. </div>
    871. 

  871. <div class="sect3">
    872. 

  872. <h4 id="_code_folding"><a class="anchor" href="#_code_folding"></a>4.3.7. Code Folding</h4>
    873. 

  873. <div class="paragraph">
    874. 

  874. <p>折叠部分非核心代码，例如Java代码的import或者getter、setter</p>
    875. 

  875. </div>
    876. 

  876. <div class="listingblock">
    877. 

  877. <div class="content">
    878. 

  878. <pre class="highlight"><code class="language-java" data-lang="java"><span class="fold-block">public class Example {
    879. 

  879. 

  880. 	private String first;
    881. 

  881. 

  882. 	private String second;
    883. 

  883. 

  884. </span><span class="fold-block hide-when-unfolded">	// getters / setters...
    885. 

  885. 

  886. </span><span class="fold-block hide-when-folded">	public String getFirst() {
    887. 

  887. 		return this.first;
    888. 

  888. 	}
    889. 

  889. 

  890. 	public void setFirst(String first) {
    891. 

  891. 		this.first = first;
    892. 

  892. 	}
    893. 

  893. 

  894. 	public String getSecond() {
    895. 

  895. 		return this.second;
    896. 

  896. 	}
    897. 

  897. 

  898. 	public void setSecond(String second) {
    899. 

  899. 		this.second = second;
    900. 

  900. 	}
    901. 

  901. 

  902. </span><span class="fold-block">}
    903. 

  903. </span></code></pre>
    904. 

  904. </div>
    905. 

  905. </div>
    906. 

  906. </div>
    907. 

  907. <div class="sect3">
    908. 

  908. <h4 id="_different_config_blocks"><a class="anchor" href="#_different_config_blocks"></a>4.3.8. Different Config Blocks</h4>
    909. 

  909. <div class="paragraph">
    910. 

  910. <p>configblocks用于生成同一配置的yaml格式和properties格式，例如下面的源文件和渲染后效果</p>
    911. 

  911. </div>
    912. 

  912. <div class="listingblock">
    913. 

  913. <div class="content">
    914. 

  914. <pre>[source,yaml,configblocks]
    915. 

  915. ----
    916. 

  916. example:
    917. 

  917.   property:
    918. 

  918.     alpha: a
    919. 

  919. ----</pre>
    920. 

  920. </div>
    921. 

  921. </div>
    922. 

  922. <div class="listingblock primary">
    923. 

  923. <div class="title">Properties</div>
    924. 

  924. <div class="content">
    925. 

  925. <pre class="highlight"><code class="language-properties" data-lang="properties">example.property.alpha=a</code></pre>
    926. 

  926. </div>
    927. 

  927. </div>
    928. 

  928. <div class="listingblock secondary">
    929. 

  929. <div class="title">Yaml</div>
    930. 

  930. <div class="content">
    931. 

  931. <pre class="highlight"><code class="language-yaml" data-lang="yaml">example:
    932. 

  932.   property:
    933. 

  933.     alpha: a</code></pre>
    934. 

  934. </div>
    935. 

  935. </div>
    936. 

  936. <div class="admonitionblock note">
    937. 

  937. <table>
    938. 

  938. <tr>
    939. 

  939. <td class="icon">
    940. 

  940. <i class="fa icon-note" title="Note"></i>
    941. 

  941. </td>
    942. 

  942. <td class="content">
    943. 

  943. 此功能还需要添加 <code>io.spring.asciidoctor:spring-asciidoctor-extensions-spring-boot</code> 依赖，参考 <a href="https://github.com/spring-io/spring-asciidoctor-extensions">spring-asciidoctor-extensions</a>
    944. 

  944. </td>
    945. 

  945. </tr>
    946. 

  946. </table>
    947. 

  947. </div>
    948. 

  948. </div>
    949. 

  949. </div>
    950. 

  950. <div class="sect2">
    951. 

  951. <h3 id="_bilibili_extension"><a class="anchor" href="#_bilibili_extension"></a>4.4. Bilibili Extension</h3>
    952. 

  952. <div class="paragraph">
    953. 

  953. <p>文档中插入视频是很常见的需求，可能是需要记录视频教程的学习笔记，也可能是使用视频对文档的内容做进一步说明。
    954. 

  954. 默认Asciidoctor仅支持在文档中插入Youtube、vimeo视频或者本地视频文件，但国内开发者更多使用的是Bilibili，
    955. 

  955. 因此开发了 <code>asciidoctor-bilibili-extension</code> 用于向AsciiDoc文档中插入Bilibili视频，
    956. 

  956. 详细用法参考 <a href="https://github.com/pxzxj/asciidoctor-bilibili-extension">asciidoctor-bilibili-extension</a>。</p>
    957. 

  957. </div>
    958. 

  958. <div class="videoblock"><div class="content">
    959. 

  959. <iframe width="640" height="480" src="https://player.bilibili.com/player.html?bvid=BV12t411m7RV&high_quality=1&page=1"  border="0" frameborder="no" framespacing="0" scrolling="no" allowfullscreen="true"></iframe>
    960. 

  960. </div></div>
    961. 

  961. </div>
    962. 

  962. </div>
    963. 

  963. </div>
    964. 

  964. <div class="sect1">
    965. 

  965. <h2 id="_examples"><a class="anchor" href="#_examples"></a>5. Examples</h2>
    966. 

  966. <div class="sectionbody">
    967. 

  967. <div class="paragraph">
    968. 

  968. <p>Asciidoctor提供了大量的 <a href="https://github.com/asciidoctor/asciidoctor-maven-examples">Maven示例</a>用于说明相关功能，本文选择常用的几类进行说明</p>
    969. 

  969. </div>
    970. 

  970. <div class="sect2">
    971. 

  971. <h3 id="_html"><a class="anchor" href="#_html"></a>5.1. Html</h3>
    972. 

  972. <div class="paragraph">
    973. 

  973. <p>参考 <a href="https://github.com/asciidoctor/asciidoctor-maven-examples/tree/main/asciidoc-to-html-example">asciidoc-to-html-example</a>，也可以参考<a href="#cicd">CI/CD示例</a>。</p>
    974. 

  974. </div>
    975. 

  975. </div>
    976. 

  976. <div class="sect2">
    977. 

  977. <h3 id="_pdf"><a class="anchor" href="#_pdf"></a>5.2. Pdf</h3>
    978. 

  978. <div class="paragraph">
    979. 

  979. <p>参考 <a href="https://github.com/asciidoctor/asciidoctor-maven-examples/tree/main/asciidoctor-pdf-cjk-example">asciidoctor-pdf-cjk-example</a>，也可以参考<a href="#cicd">CI/CD示例</a>。</p>
    980. 

  980. </div>
    981. 

  981. </div>
    982. 

  982. <div class="sect2">
    983. 

  983. <h3 id="cicd"><a class="anchor" href="#cicd"></a>5.3. CI/CD</h3>
    984. 

  984. <div class="paragraph">
    985. 

  985. <p><code>Docs as Code</code> 要求文档同代码一样能够在CI/CD流水线中自动发布，例如可以将生成的html文件部署到nginx搭建的站点上就可以直接在浏览器中查看文档了，
    986. 

  986. 由于文档是使用Maven插件生成的，因此整个发布过程与普通Java项目没有任何区别。
    987. 

  987. 本文使用 <code>GitHub Action</code> 以及 <code>GitHub Pages</code> 演示CI/CD过程，示例代码参考 <a href="https://github.com/pxzxj/asciidoc-cicd-demo">asciidoc-cicd-demo</a>。</p>
    988. 

  988. </div>
    989. 

  989. </div>
    990. 

  990. <div class="sect2">
    991. 

  991. <h3 id="_doc_review"><a class="anchor" href="#_doc_review"></a>5.4. Doc Review</h3>
    992. 

  992. <div class="paragraph">
    993. 

  993. <p>代码需要评审，文档也一样，通过文档评审可以逐步提升文档质量以及团队文档编写能力。</p>
    994. 

  994. </div>
    995. 

  995. <div class="paragraph">
    996. 

  996. <p>GitHub和GitLab都提供了强大的 <code>Review</code> 功能，可以对PR的内容进行评审和讨论，只有评审通过的内容才会合并。
    997. 

  997. 以Spring Boot项目中的一个对 <code>README.adoc</code> 润色的 <a href="https://github.com/spring-projects/spring-boot/pull/28835">PR</a>为例，
    998. 

  998. Spring成员查看提交的内容并提出疑问，原作者进行回复</p>
    999. 

  999. </div>
    1000. 

  1000. <div class="imageblock">
    1001. 

  1001. <div class="content">
    1002. 

  1002. <img src="images/doc-review.png" alt="doc review">
    1003. 

  1003. </div>
    1004. 

  1004. </div>
    1005. 

  1005. </div>
    1006. 

  1006. </div>
    1007. 

  1007. </div>
    1008. 

  1008. <div class="sect1">
    1009. 

  1009. <h2 id="_style"><a class="anchor" href="#_style"></a>6. Style</h2>
    1010. 

  1010. <div class="sectionbody">
    1011. 

  1011. <div class="paragraph">
    1012. 

  1012. <p>上文主要讨论了编写技术文档使用的工具，而文档编写的另一个重要主题是写作规范，
    1013. 

  1013. 使用陈述句还是祈使句、使用第一人称还是第二人称等等这些语法细节也会影响最终文档的质量。</p>
    1014. 

  1014. </div>
    1015. 

  1015. <div class="paragraph">
    1016. 

  1016. <p>Spring就非常重视文档写作规范， <a href="https://github.com/spring-io/spring-asciidoctor-backends/blob/main/guides/style-guide.adoc">spring-style</a>详细描述了编写Spring技术文档相关规范，
    1017. 

  1017. 同时还根据开发者反馈对文档不断进行 <a href="https://github.com/spring-projects/spring-boot/issues/27895">优化</a>，可以说完善的文档也是Spring框架如此成功的重要原因之一。</p>
    1018. 

  1018. </div>
    1019. 

  1019. <div class="paragraph">
    1020. 

  1020. <p>Kubernetes的文档规范参考 <a href="https://kubernetes.io/docs/contribute/style/style-guide/">Documentation Style Guide</a></p>
    1021. 

  1021. </div>
    1022. 

  1022. <div class="paragraph">
    1023. 

  1023. <p>中文技术领域目前比较受开发者认可的是由阮一峰编写的 <a href="https://www.ruanyifeng.com/blog/2016/10/document_style_guide.html">中文技术文档的写作规范</a>，GitHub的Star数量已经接近一万。</p>
    1024. 

  1024. </div>
    1025. 

  1025. </div>
    1026. 

  1026. </div>
    1027. 

  1027. <div class="sect1">
    1028. 

  1028. <h2 id="_best_practice"><a class="anchor" href="#_best_practice"></a>7. Best Practice</h2>
    1029. 

  1029. <div class="sectionbody">
    1030. 

  1030. <div class="olist arabic">
    1031. 

  1031. <ol class="arabic">
    1032. 

  1032. <li>
    1033. 

  1033. <p>先列举文档的目录，再补充各章节的内容。</p>
    1034. 

  1034. </li>
    1035. 

  1035. <li>
    1036. 

  1036. <p>参考优秀的开源项目文档。</p>
    1037. 

  1037. </li>
    1038. 

  1038. <li>
    1039. 

  1039. <p>内容为王，时间紧急情况下优先保证内容，其次考虑格式美观。</p>
    1040. 

  1040. </li>
    1041. 

  1041. <li>
    1042. 

  1042. <p><strong>写</strong>，立即开始。</p>
    1043. 

  1043. </li>
    1044. 

  1044. </ol>
    1045. 

  1045. </div>
    1046. 

  1046. </div>
    1047. 

  1047. </div>
    1048. 

  1048. </div>
    1049. 

  1049. <div id="footer">
    1050. 

  1050. <div id="footer-text">
    1051. 

  1051. Last updated 2024-03-18 05:44:42 UTC
    1052. 

  1052. </div>
    1053. 

  1053. </div>
    1054. 

  1054. <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.3/highlight.min.js"></script>
    1055. 

  1055. <script>
    1056. 

  1056. if (!hljs.initHighlighting.called) {
    1057. 

  1057.   hljs.initHighlighting.called = true
    1058. 

  1058.   ;[].slice.call(document.querySelectorAll('pre.highlight > code')).forEach(function (el) { hljs.highlightBlock(el) })
    1059. 

  1059. }
    1060. 

  1060. </script>
    1061. 

  1061. <script src="https://utteranc.es/client.js"
    1062. 

  1062.         repo="pxzxj/articles"
    1063. 

  1063.         issue-term="title"
    1064. 

  1064.         label="utteranc"
    1065. 

  1065.         theme="github-light"
    1066. 

  1066.         crossorigin="anonymous"
    1067. 

  1067.         async>
    1068. 

  1068. </script>
    1069. 

  1069. </div>
    1070. 

  1070.   </div>
    1071. 

  1071. </div>
    1072. 

  1072. </body>
    1073. 

  1073. </html>
    1074.