如何在 Markdown 格式的 YARD 文档中插入项目符号 (<li>) 元素答案

【问题标题】：How can I insert a bullet (<li>) element in Markdown-formatted YARD documentation如何在 Markdown 格式的 YARD 文档中插入项目符号 (<li>) 元素
【发布时间】：2013-05-14 07:12:45
【问题描述】：

我正在使用 YARDoc 和 Markdown 来记录我的 Ruby 代码，并且希望在方法的文档中包含一个无序列表（HTML“项目符号”）。到目前为止，这是我所拥有的：

$ cat file.rb
class Foo
  # Returns "foo", which consists of the letters:
  # * f
  # * o
  # * o
  def method; "foo"; end
end

我正在使用以下方法生成文档：

$ yard doc --markup markdown file.rb

但它不会生成 HTML 项目符号，它将星号 (*) 视为文字字符。生成的doc/Foo.html 文件包含：

<span class="summary_desc"><div class='inline'><p>Returns &quot;foo&quot;,
which consists of the letters:
* f
* o
* o.</p>
</div></span>

如何在 YARD 中使用 Markdown 插入 HTML 项目符号？我基本上希望上述输出中的每个字母都包含在 <li>...</li> 中，并且列表由 <ul> 元素包围。

【问题讨论】：

标签： ruby documentation markdown yard

【解决方案1】：

我需要一个空行分隔第一行文本和列表的开头：

$ cat file.rb 
class Foo
  # Returns "foo", which consists of the letters:
  #
  # * f
  # * o
  # * o
  def method; "foo"; end
end

产生：

<div class="discussion">
  <p>Returns &quot;foo&quot;, which consists of the letters:</p>
  <ul>
    <li>f</li>
    <li>o</li>
    <li>o</li>
  </ul>
</div>

【讨论】：

【解决方案2】：

$ cat file.rb
class Foo
  # Returns "foo", which consists of the letters:

* f
* o
* o
^

  def method; "foo"; end
end

$ kramdown file.rb
<p>class Foo
  # Returns "foo", which consists of the letters:</p>

<ul>
  <li>f</li>
  <li>o</li>
  <li>o</li>
</ul>

<p>def method; "foo"; end
end</p>

http://kramdown.rubyforge.org/syntax.html#block-ials

【讨论】：