[SOLVED] Convert markdown to html with a table of contents using Redcarpet

Convert markdown to html with a table of contents using Redcarpet

My goal is to convert a markdown document to html, with a table of contents at the top. I saw that Redcarpet has a HTML_TOC option, which is really nice. But when I use it, it only renders the TOC, it does not include the rest of the document.

renderer = Redcarpet::Render::HTML_TOC.new(with_toc_data: true)
markdown = Redcarpet::Markdown.new(renderer)
html = markdown.render(File.read(input_file))

How do I render both the TOC and document itself in the same html page?

The only thing I can think of is to render two separate html objects, then combine them. But that is a little messy because I'd have to parse out the head/body tags properly before combining them. Is there a better way?

Solution

The only thing I can think of is to render two separate html objects, then combine them.

That would be exactly what you need to do. As a reminder, Markdown does not render a complete HTML document anyway. You only get an HTML fragment. For example a simple Markdown document:

A simple Markdown document.

gets rendered as the following HTML fragment:

<p>A simple Markdown document.</p>

However, for a complete, valid HTML document you need (at least) the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Page Title</title>
  </head>
  <body>
    <p>A simple Markdown document.</p>
  </body>
</html>

Considering that you need to generate all of that anyway, how is it "messy" to obtain the TOC and the body separately?

In fact, in more sophisticated systems, the TOC may be in a sidebar or something. Therefore, using a templating system, the TOC can be passed to a template separately anyway, where it is then placed in a container which separates it from the document body for positioning and styling by CSS.

The exact template syntax might vary depending on which tools you use, but perhaps something like this:

<!DOCTYPE html>
<html>
  <head>
    <title>{{ page.title }}</title>
  </head>
  <body>
    <aside>
      {{ page.toc }}
    </aside>
    <div id="body">
      {{ page.body }}
    </div>
  </body>
</html>

Of course, you don't have to use a template, but is certainly is a "clean" way to generate a document.