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

生成

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

删除线¶ ↑

示例

This is ~~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: 支持的扩展

公共类方法

new (extensions = DEFAULT_EXTENSIONS, debug = false)

源代码

# File lib/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

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

parse (markdown)

源代码

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

  parser.parse markdown
end

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

公共实例方法

emphasis (text)

源代码

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

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

link_to (content, label = content, text = nil)

源代码

# File lib/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

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

list_item_from (unparsed)

源代码

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

通过解析第一次解析过程中的 unparsed 内容来创建 RDoc::Markup::ListItem。

note (label)

源代码

# File lib/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

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

note_for (ref)

源代码

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

  label = @note_order.length

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

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

paragraph (parts)

源代码

# File lib/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

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

parse (markdown)

源代码

# File lib/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

将 markdown 解析为 RDoc::Document

reference (label, link)

源代码

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

  @references[label] = link
end

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

strong (text)

源代码

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

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

扩展

↑ 顶部

公共类方法

extension (name)

源代码

# File lib/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

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

公共实例方法

break_on_newline ()

源代码

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

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

css ()

源代码

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

允许样式块

definition_lists ()

源代码

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

允许 PHP Markdown 额外的样式定义列表

extension (name, enable)

源代码

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

启用或禁用具有 name 的扩展

extension? (name)

源代码

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

是否启用了扩展 name？

github ()

源代码

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

允许 Github Flavored Markdown

html ()

源代码

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

允许 HTML

notes ()

源代码

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

启用注释扩展

strike ()

源代码

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

启用删除线扩展