Question

我使用Github Flavoured markdown（GFM）编写的一些文档制作了一个宝石，以利用它们的语法高亮。

不幸的是，Github决定使用他们自己的语法进行代码块防护（三个反引号），以便让Yardoc正确解析我选择了Kramdown作为解析器，supports GFM。

最重要的是，当我将代码推送到Rubygems时，将通过运行Rake任务生成文档（据我所知）。因此，我需要找到一种方法告诉Yard使用Kramdown GFM解析器，通过Rake。

Kramdown通过-i开关选择解析器：

$ bin/kramdown --help

Command line options:

    -i, --input ARG
          Specify the input format: kramdown (default), html, GFM or markdown

但我不知道如何让Yard通过yard二进制文件或通过Rake传递它。我想这可以通过创建一个Yardoc插件来实现，但是我从来没有这样做过，也不确定它是否会起作用，而且看起来事情也会在那时失控！

我真正喜欢的是降价标准，但这不是一个问题，而是一个未实现的愿望......我不确定StackOverflow可以帮助那么多。

对此的任何帮助将不胜感激。

Answer 1

我最近遇到了这个问题，在任何地方都找不到清晰的指导，因此在深入了解Yard的问题和来源之后，我想到了这种方法，并且对此感到非常满意。希望它可能对遇到此线程的其他人有所帮助。

添加一个用于Yard定制的Ruby文件。如果docs/文件夹中还有其他文档，那么docs/yard_support.rb可能是个好地方。在其中，为Yard添加自定义标记提供程序。

# docs/yard_support.rb
require 'kramdown'
require 'kramdown-parser-gfm'

# Custom markup provider class that always renders Kramdown using GFM (Github
# Flavored Markdown). You could add additional customizations here, or even
# call a different Markdown library altogether, like `commonmarker`.
# The only requirement is that your class supports:
#   - `#initialize(markdown_text, options_hash)`
#   - `#to_html()`, which just returns the converted HTML source
class KramdownGfmDocument < Kramdown::Document
    def initialize(source, options = {})
        options[:input] = 'GFM' unless options.key?(:input)
        super(source, options)
    end
end

# Register the new provider as the highest priority option for Markdown.
# Unfortunately there's no nice interface for registering your provider; you
# just have to insert it directly at the front of the array. :\
# See also:
# - https://github.com/lsegal/yard/issues/1157
# - https://github.com/lsegal/yard/issues/1017
# - https://github.com/lsegal/yard/blob/main/lib/yard/templates/helpers/markup_helper.rb
YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].insert(
    0,
    { const: 'KramdownGfmDocument' }
)

在--load <path_to_the_above_file>文件中使用.yardopts：
```
# .yardopts
--load docs/yard_support.rb
```

如何通过Rake到Yard向Kramdown传递选项以使用GFM

1 个答案: