Skip to content

Recognize Github Flavored Markdown #404

bytesource opened this Issue Oct 30, 2011 · 20 comments

9 participants


In my README files I use features from Github Flavored Markdown, such as code highlighting and awareness for underscores inside a word, but YARD does not recognize them.

Adding github-markup as a markup provider to .yardopts

-M github-markup

resulted in an error:

[error]: Invalid markup type 'markdown' or markup provider (github-markup) is not registered.

yard-0.7.3/lib/yard/templates/helpers/html_helper.rb:70:in `html_markup_markdown': undefined method `new' for nil:NilClass (NoMethodError)

Is there a way to make YARD parse Github Flavored Markdown? If not, I would suggest this as a new feature, especially because services like fetch their data from Github repos.


lsegal commented Oct 30, 2011

It works, but it relies on the redcarpet lib, use -M redcarpet.

@lsegal lsegal closed this Oct 30, 2011

GFM is working now, thank you very much!

lsegal commented Oct 30, 2011

No problem :)


While YARD worked well with GitHub Flavored Markup locally after adding -M redcarpet to .yardopts, I realized that GFM still is not displayed correctly on

This is the content of my .yardopts file:



This is how the README should look like:
This is how it is displayed on

Did I miss something or is the option -M redcarpet not recognized on


Same issue here, identical yarddoc as @bytesource.

lsegal commented Nov 10, 2011

This is probably a issue, we should open one on


@lsegal I just did....:-)

nikosd commented Nov 22, 2011

just for the record (in case someone in the future reads this like me) here's what it takes to make this work :

In your Gemfile:

  gem 'yard'
  gem 'redcarpet'
  gem 'github-markup'

In your .yardopts




Is there a way to use redcarpet/markdown for the README but rdoc for the source files?

ghost commented Nov 26, 2011

Append .md to your README, and use -m rdoc in .yardopts.

And nope, I don't think it is possible to specify the provider for markdown if your source markup language is rdoc, but you could try with -M redcarpet.

lsegal commented Nov 26, 2011

@robgleeson @alindeman Note that this would require you to not have redcloth, kramdown, or bluecloth installed as a gem, or, if you are loading yard from bundler (bundle exec yard), only list the above gems in your gemfile. Unfortunately we don't currently bundle exec from, and already have rdiscount installed, so this wouldn't work there. It's possible we might change the priority order for gems given the rising popularity for GFM.


Nice, this works as long as rdiscount is not installed. Thanks for the tip.

$ yardoc */lib/**/*.rb -

Definitely +1 for Github Flavored Markup in Thanks again all!


Hmm...I can't get this to work at all :(.

I followed the instructions that @nikosd gave above. Can someone tell me what I'm doing wrong? My attempt to use GFM is here.

lsegal commented Dec 22, 2011

Hmm...I can't get this to work at all :(.

I can't reproduce it not working. Note that the --markup-provider is no longer necessary as redcarpet is the default markdown provider now. Are you just looking to highlight a readme? Can you point to the specific parts that aren't working?


Here's what I'm seeing in my local browser:


It looks like it's working on so I'm not sure what I'm doing wrong :(.

Here's my shell output from what I'm doing. Note that I'm deleting doc and .yardoc just in case I have some old artifacts that are preventing this form working (but it doesn't seem to make a difference either way).

➜  vcr git:(master) rm -rf doc
➜  vcr git:(master) rm -rf .yardoc
➜  vcr git:(master) yard doc
[warn]: Syntax error in `license`:(1,18): syntax error, unexpected tinteger, expecting $end
[warn]: in YARD::Handlers::Ruby::MethodHandler: Undocumentable method defined on object instance
[warn]:     in file 'lib/vcr/cassette/migrator.rb':49:

    49: def hash.each

yardFiles:          25
Modules:        10 (    0 undocumented)
Classes:        22 (    0 undocumented)
Constants:       3 (    0 undocumented)
Methods:        93 (   14 undocumented)
 89.06% documented
➜  vcr git:(master) yard server
>> YARD 0.7.4 documentation server at
[2011-12-22 12:14:52] INFO  WEBrick 1.3.1
[2011-12-22 12:14:52] INFO  ruby 1.9.2 (2011-07-09) [x86_64-darwin10.8.0]
[2011-12-22 12:14:52] INFO  WEBrick::HTTPServer#start: pid=7477 port=8808 - - [22/Dec/2011:12:15:01 PST] "GET /docs/file/ HTTP/1.1" 200 11733
http://localhost:8808/ -> /docs/file/ - - [22/Dec/2011:12:15:01 PST] "GET /css/custom.css HTTP/1.1" 200 2209
http://localhost:8808/docs/file/ -> /css/custom.css - - [22/Dec/2011:12:15:01 PST] "GET /css/common.css HTTP/1.1" 200 42 - - [22/Dec/2011:12:15:01 PST] "GET /js/jquery.js HTTP/1.1" 200 85925
http://localhost:8808/docs/file/ -> /css/common.css - - [22/Dec/2011:12:15:01 PST] "GET /js/app.js HTTP/1.1" 200 6492 - - [22/Dec/2011:12:15:01 PST] "GET /css/style.css HTTP/1.1" 200 17034
http://localhost:8808/docs/file/ -> /js/jquery.js
http://localhost:8808/docs/file/ -> /js/app.js
http://localhost:8808/docs/file/ -> /css/style.css - - [22/Dec/2011:12:15:01 PST] "GET /js/autocomplete.js HTTP/1.1" 200 8003
http://localhost:8808/docs/file/ -> /js/autocomplete.js - - [22/Dec/2011:12:15:01 PST] "GET /js/live.js HTTP/1.1" 200 1031
http://localhost:8808/docs/file/ -> /js/live.js - - [22/Dec/2011:12:15:01 PST] "GET /favicon.ico HTTP/1.1" 200 0
- -> /favicon.ico
obrie commented Dec 31, 2011

I'm also having no luck with this. I've created the following project:

In that project, I've listed the gems installed (via gem list), the command used (bundle exec yard), and the generated output (in the output folder).

Any thoughts?

edit: May also be worth noting that this was generated using Ruby 1.8.7

lsegal commented Dec 31, 2011

You should be using redcarpet 1.x, 2.x is not yet compatible with YARD. (2.x was released after 0.7.4 was)

obrie commented Dec 31, 2011

Bingo -- that was it. Thanks!


Further to this (in case it helps anyone) - I was having problems using "bundle exec yardoc" because although I had changed my Gemfile to use redcarpet 1.x, redcarpet 2.x was still on my system.

I believe you need to gem uninstall redcarpet 2.x for it to work (I guess it's simply shelling out to the redcarpet command)

weakish commented Nov 24, 2014

I was having problems using "bundle exec yardoc" because although I had changed my Gemfile to use redcarpet 1.x, redcarpet 2.x was still on my system.

I encountered a similar problem.

After uninstalling redcarpet 3.x and install 2.3.0, GFM works.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.