class RDoc::Markdown

RDoc::Markdown，如 markdown 语法所述。

要选择 Markdown 作为唯一的默认格式，请参阅 RDoc::Options 中的“已保存的选项”，获取有关设置 .rdoc_options 文件以存储项目默认值的说明。

用法¶ ↑

这是一个使用此解析器手动读取 markdown 文件的简短示例。

data = File.read("README.md")
formatter = RDoc::Markup::ToHtml.new(RDoc::Options.new, nil)
html = RDoc::Markdown.parse(data).accept(formatter)

# do something with html

扩展¶ ↑

解析器支持以下 markdown 扩展，但并非所有扩展都默认用于 RDoc 输出。

`RDoc`¶ ↑

RDoc Markdown 解析器具有以下内置行为，无法禁用。

嵌入在单词中的下划线永远不会被解释为强调。(虽然 markdown dingus 强调单词中的下划线，但 Markdown 语法和 MarkdownTest 都没有提到此行为。)

对于 HTML 输出，RDoc 始终自动链接裸 URL。

换行符断行¶ ↑

break_on_newline 扩展会将所有换行符转换为硬换行符，如 Github Flavored Markdown 中所示。此扩展默认情况下处于禁用状态。

CSS¶ ↑

css 扩展允许在输出中包含 CSS 块，但它们不用于任何内置的 RDoc 输出格式。此扩展默认情况下处于禁用状态。

示例

<style type="text/css">
h1 { font-size: 3em }
</style>

定义列表¶ ↑

definition_lists 扩展允许使用 PHP Markdown Extra 语法的定义列表，但目前仅支持一个标签和一个定义。此扩展默认情况下处于启用状态。

示例

cat
:   A small furry mammal
that seems to sleep a lot

ant
:   A little insect that is known
to enjoy picnics

生成

猫: 一种似乎经常睡觉的小型毛茸茸的哺乳动物
蚂蚁: 一种喜欢野餐的小昆虫

删除线¶ ↑

示例

This is ~~striked~~.

生成

这是 ~striked~。

Github¶ ↑

github 扩展启用了一部分 Github Flavored Markdown。此扩展默认情况下处于启用状态。

支持的 github 扩展包括

围栏代码块¶ ↑

在代码块周围使用 ```，而不是缩进四个空格。

语法高亮¶ ↑

使用 ``` ruby 作为代码围栏的开头来添加语法高亮。(目前仅支持 ruby 语法)。

HTML¶ ↑

允许在输出中包含原始 HTML。此扩展默认情况下处于启用状态。

示例

<table>
...
</table>

注释¶ ↑

notes 扩展启用脚注支持。此扩展默认情况下处于启用状态。

示例

Here is some text[^1] including an inline footnote ^[for short footnotes]

...

[^1]: With the footnote text down at the bottom

生成

这是一些文本¹，包括一个内联脚注 ²

限制¶ ↑

链接标题未使用
脚注被折叠成一个段落

作者¶ ↑

此 markdown 解析器是从 John MacFarlane 的 peg-markdown 移植到 kpeg 的。

它在 MIT 许可证下使用

特此授予任何获得本软件和相关文档文件（“软件”）副本的人免费许可，以不受限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，并允许向其提供本软件的人员这样做，但须遵守以下条件

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于对适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是因合同、侵权行为或其他原因引起的，还是由本软件或本软件的使用或其他交易引起的。

移植到 kpeg 是由 Eric Hodel 和 Evan Phoenix 执行的

¹ 脚注文本在底部

² 用于短脚注

常量

DEFAULT_EXTENSIONS: 默认启用的扩展
EXTENSIONS: 支持的扩展
HTML_ENTITIES: RDoc::Markdown 的 HTML 实体名称映射

公共类方法

new(extensions = DEFAULT_EXTENSIONS, debug = false) 单击以切换源

创建一个新的 markdown 解析器，该解析器启用给定的 extensions。

# File rdoc/markdown.rb, line 668
def initialize extensions = DEFAULT_EXTENSIONS, debug = false
  @debug      = debug
  @formatter  = RDoc::Markup::ToJoinedParagraph.new
  @extensions = extensions

  @references          = nil
  @unlinked_references = nil

  @footnotes       = nil
  @note_order      = nil
end

也别名为：orig_initialize

parse(markdown) 单击以切换源

使用默认扩展将 markdown 文档解析为 RDoc::Document。

# File rdoc/markdown.rb, line 656
def self.parse markdown
  parser = new

  parser.parse markdown
end

公共实例方法

emphasis(text) 单击以切换源

将 text 包装在 rdoc 内联格式的强调中

# File rdoc/markdown.rb, line 683
def emphasis text
  if text =~ /\A[a-z\d.\/]+\z/i then
    "_#{text}_"
  else
    "<em>#{text}</em>"
  end
end

link_to(content, label = content, text = nil) 单击以切换源

查找 label 的链接引用，并使用 content 作为链接文本创建指向该引用的新链接。如果在引用收集解析器传递中没有遇到 label，则使用链接 text（通常是空格）重建标签和内容。

# File rdoc/markdown.rb, line 737
def link_to content, label = content, text = nil
  raise ParseError, 'enable notes extension' if
    content.start_with? '^' and label.equal? content

  if ref = @references[label] then
    "{#{content}}[#{ref}]"
  elsif label.equal? content then
    "[#{content}]#{text}"
  else
    "[#{content}]#{text}[#{label}]"
  end
end

list_item_from(unparsed) 单击以切换源

通过解析第一次解析传递中的 unparsed 内容，创建 RDoc::Markup::ListItem。

# File rdoc/markdown.rb, line 754
def list_item_from unparsed
  parsed = inner_parse unparsed.join
  RDoc::Markup::ListItem.new nil, *parsed
end

note(label) 单击以切换源

将 label 存储为注释，并填写先前未知的注释引用。

# File rdoc/markdown.rb, line 762
def note label
  #foottext = "rdoc-label:foottext-#{label}:footmark-#{label}"

  #ref.replace foottext if ref = @unlinked_notes.delete(label)

  @notes[label] = foottext

  #"{^1}[rdoc-label:footmark-#{label}:foottext-#{label}] "
end

note_for(ref) 单击以切换源

为脚注 reference 创建一个新链接，并将引用添加到注释顺序列表，以便在文档末尾正确显示。

# File rdoc/markdown.rb, line 776
def note_for ref
  @note_order << ref

  label = @note_order.length

  "{*#{label}}[rdoc-label:foottext-#{label}:footmark-#{label}]"
end

orig_initialize(extensions = DEFAULT_EXTENSIONS, debug = false)

TODO 在 kpeg 0.10 发布后删除

别名为：new

paragraph(parts) 单击以切换源

从 parts 创建 RDoc::Markup::Paragraph，并包括特定于扩展的行为

# File rdoc/markdown.rb, line 793
def paragraph parts
  parts = parts.map do |part|
    if "\n" == part then
      RDoc::Markup::HardBreak.new
    else
      part
    end
  end if break_on_newline?

  RDoc::Markup::Paragraph.new(*parts)
end

parse(markdown) 单击以切换源

将 markdown 解析为 RDoc::Document

# File rdoc/markdown.rb, line 808
def parse markdown
  @references          = {}
  @unlinked_references = {}

  markdown += "\n\n"

  setup_parser markdown, @debug
  peg_parse 'References'

  if notes? then
    @footnotes       = {}

    setup_parser markdown, @debug
    peg_parse 'Notes'

    # using note_order on the first pass would be a bug
    @note_order      = []
  end

  setup_parser markdown, @debug
  peg_parse

  doc = result

  if notes? and not @footnotes.empty? then
    doc << RDoc::Markup::Rule.new(1)

    @note_order.each_with_index do |ref, index|
      label = index + 1
      note = @footnotes[ref] or raise ParseError, "footnote [^#{ref}] not found"

      link = "{^#{label}}[rdoc-label:footmark-#{label}:foottext-#{label}] "
      note.parts.unshift link

      doc << note
    end
  end

  doc.accept @formatter

  doc
end

也别名为：peg_parse

peg_parse(markdown)

内部 kpeg 解析方法

别名为：parse

reference(label, link) 单击以切换源

将 label 存储为对 link 的引用，并填写先前未知的链接引用。

# File rdoc/markdown.rb, line 855
def reference label, link
  if ref = @unlinked_references.delete(label) then
    ref.replace link
  end

  @references[label] = link
end

strong(text) 单击以切换源

将 text 包装在 rdoc 内联格式的粗体标记中

# File rdoc/markdown.rb, line 866
def strong text
  if text =~ /\A[a-z\d.\/-]+\z/i then
    "*#{text}*"
  else
    "<b>#{text}</b>"
  end
end

扩展

↑ 顶部

公共类方法

extension(name) 单击以切换源

为 name 扩展创建扩展方法，以启用和禁用扩展并查询它们是否处于活动状态。

# File rdoc/markdown.rb, line 603
def self.extension name
  EXTENSIONS << name

  define_method "#{name}?" do
    extension? name
  end

  define_method "#{name}=" do |enable|
    extension name, enable
  end
end

公共实例方法

break_on_newline() 单击以切换源

将所有换行符转换为硬换行符

# File rdoc/markdown.rb, line 618
extension :break_on_newline

css() 单击以切换源

允许样式块

# File rdoc/markdown.rb, line 623
extension :css

definition_lists() 单击以切换源

允许 PHP Markdown Extras 样式定义列表

# File rdoc/markdown.rb, line 628
extension :definition_lists

extension(name, enable) 单击以切换源

使用 name 启用或禁用扩展

# File rdoc/markdown.rb, line 705
def extension name, enable
  if enable then
    @extensions |= [name]
  else
    @extensions -= [name]
  end
end

extension?(name) 单击以切换源

是否启用了扩展 name？

# File rdoc/markdown.rb, line 696
def extension? name
  @extensions.include? name
end

github() 单击以切换源

允许 Github Flavored Markdown

# File rdoc/markdown.rb, line 633
extension :github

html() 单击以切换源

允许 HTML

# File rdoc/markdown.rb, line 638
extension :html

notes() 单击以切换源

启用注释扩展

# File rdoc/markdown.rb, line 643
extension :notes

strike() 点击切换源代码

启用删除线扩展

# File rdoc/markdown.rb, line 648
extension :strike