Search code examples
github-pageskramdown

Github-pages/kramdown won't render my mixed markdown/html correctly

I've got a mixed HTML/Markdown page that I thought was pretty simple, but Github-pages giving inexplicable renderings.

It's configured to use kramdown/GFM.

This is the piece of code that's getting me:

QuickFIX Settings
-----------------

* [Session](#session)
* [Validation](#validation)
* [Initiator](#initiator)
* [Acceptor](#acceptor)
* [Socket Configuration](#socketConfiguration)
* [Storage](#storage)
* [File Storage](#file)
* [Logging](#logging)
* [SSL](#ssl)
* [Sample Settings File](#sample)

<a name="session"/>

## Session

<table>
  <tr>
    <th>Setting</th>
    <th>Description</th>
    <th>Valid Values</th>
    <th>Default</th>
  </tr>

[more table code follows...]

When I preview the markdown code in other Markdown parsers (e.g. the Issue description parser), it's fine. But when I push it to the gh-pages branch, I get this kind of garbage:

screenshot of bad github-pages render

Why are those tr-close and table-close tags there? (No table even started yet!) And why does the table actually appear under the next header?

Nothing about this makes sense!

It's an open-source project, so you can see the current live render and source right here:

Solution

  • The reason why your table is broken is because of an unbalanced (unclosed) td in your table, effectively breaking the HTML flow:

      <tr>
    <td class='setting'>SendRedundantResendRequests</td>
    <td class='description'>
<!-- ^-- this td element is never closed -->
      If set to Y, QuickFIX will send all necessary resend requests, even if they appear redundant.
      Some systems will not certify the engine unless it does this.
      When set to N, QuickFIX will attempt to minimize resend requests.
      This is particularly useful on high volume systems.
    <td class='valid'>
      <div>Y</div>
      <div>N</div>
    </td>
    <td class='default'>N</td>
  </tr>