Ruby: how to generate HTML from Markdown like GitHub's or BitBucket's?

Question

On the main page of every repository in GitHub or BitBucket it shows the Readme.md in a very pretty format.

Is there a way to make the same thing with ruby? I have already found some gems like Redcarpet, but it never looks pretty. I've followed this instructions for Redcarpet.

Edit: After I tried Github's markup ruby gem, the same thing is happening. What is shown is this: And what I want is this:

And I'm sure it's not only css missing, because after 3 backquotes (```) I write the syntax like json or bash and in the first image it is written.

Edit2:

This code here:

  renderer = Redcarpet::Render::HTML.new(prettify: true)
  markdown = Redcarpet::Markdown.new(renderer, fenced_code_blocks: true)
  html = markdown.render(source_text)
  '<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>'+html

Generated this:

Sprightly

What do you mean by "looks pretty"? Sounds like you might need to define some CSS rules. – Underwood

If this is an issue of needing to define CSS, then this could be a duplicate of How to apply style for the inbuilt markdown tags? – Underwood

See also, How to apply color in Markdown. – Underwood

Thanks for the comments, you lead me to more investigation and I've edited the question adding more information. – Sprightly

Ah, you appear to be missing two pieces: Fenced code blocks are non-standard (you may need to enable them or use a different Markdown parser) and syntax highlighting (usually handled separately from Markdown). – Underwood

Answer 1

Github provides its own ruby gem to do so: https://github.com/github/markup. You just need to install the right dependencies and you're good to go.

Rhinelandpalatinate

Thanks, your comment lead me to more investigation and I've edited the question adding more information. – Sprightly

Answer 2

You need to enable a few nonstandard features.

Fenced code blocks

Fenced code blocks are nonstandard and are not enabled by default on most Markdown parsers (some older ones don't support them at all). According to Redcarpet's docs, you want to enable the fenced_code_blocks extension:

• :fenced_code_blocks: parse fenced code blocks, PHP-Markdown style. Blocks delimited with 3 or more ~ or backticks will be considered as code, without the need to be indented. An optional language name may be added at the end of the opening fence for the code block.

Syntax Highlighting

Most Markdown parsers to not do syntax highlighting of code blocks. And those that do always do it as an option. Even then, you will still need to provide your own CSS styles to have the code blocks styled properly. As it turns out, Redcarpet does include support for a prettify option to the HTML renderer:

• :prettify: add prettyprint classes to <code> tags for google-code-prettify.

You will need to get the Javascript and CSS from the google-code-prettify project to include in your pages.

Solution

In the end you'll need something like this:

renderer = Redcarpet::Render::HTML.new(prettify: true)
markdown = Redcarpet::Markdown.new(renderer, fenced_code_blocks: true)
html = markdown.render(source_text)

Underwood

Good, we have moved forward. It changed the color of the code. But there is no box yet... I've updated the post again... – Sprightly

The "box" is just a background color defined in a CSS rule. For example, here on Stackoverflow, the rule code { background-color: #eff0f1; } defines a background color for code blocks. That sort of stuff is not going to be provided by a Markdown processor. You either need to define it yourself or use some sort of framework which provides a "theme" such as a static site generator. But those things are different questions which should be asked separately. – Underwood

Thank you very much Waylan. But I can't believe that there is not a simple one or two lines of code that already makes it look identical or very similar to GitHub or BitBucket. There must be someone who already solve it.... If not there is a very good opportunity to a gem. – Sprightly

You should look at static site generators (more here). Of course, making tool recomendations is out-of-scope for Stackoverflow, so I have no further input on this question. – Underwood

Answer 3

As @yoones said Github shares their way to do it but to be more precise they use the gem "commonmarker" for markdown. Though as far as I can tell this thing does not give the full formatted HTML file but only a piece that you insert into <body>. So you can do it like I did:

require "commonmarker"

puts <<~HEREDOC
  <!DOCTYPE html>
  <html>
    <head>
      <style>#{File.read "markdown.css"}</style>
    </head>
    <body class="markdown-body Box-body">
      #{CommonMarker.render_html ARGF.read, %i{ DEFAULT UNSAFE }, %i{ table }}
    </body>
  </html>
HEREDOC

Where did I get the markdown.css? I just stole the CSS files from an arbitrary Github page with README rendered and applied UNCSS to it -- resulted in a 26kb file, you can find it in the same repo I just linked.
Why the table and UNSAFE? I need this to render an index.html for Github Pages because their markdown renderer can't newlines within table cells, etc. so instead of asking it to render my README.md I make the index.html myself.

Reiko