4

Hackage has been able to display Markdown READMEs for a while.

But as one can see for example on the Hackage page for hpack, Hackage doesn't seem to support the same table syntax as GitHub.

Markdown:

#### <a name="flags"></a>Flags

| Hpack | Cabal | Default | Notes |
| --- | --- | --- | --- |
| `description` | `description` | | Optional |
| `manual` | `manual` | | Required (unlike Cabal) |
| `default` | `default` | | Required (unlike Cabal) |

Rendered on GitHub:

enter image description here

Rendered on Hackage:

enter image description here

So, I'm wondering:

  • Which Markdown dialect does Hackage support?
  • Is there a syntax for tables in that dialect?
  • Is there a syntax for tables in the subset of Markdown that is supported by both GitHub and Hackage?
sjakobi
  • 3,546
  • 1
  • 25
  • 43
  • 5
    I am not voting to close: this doesn't appear to be a question asking for a library/tool recommendation at all, but rather a question about what tool Hackage uses. It seems perfectly on-topic to me, and well-phrased as well. – Daniel Wagner Jan 12 '17 at 22:43

1 Answers1

6

A quick search through the source of Hackage shows that is uses cheapskate (by John MacFarlane, the author of Pandoc). Looking at the Cheapskate.Types you can see everything that is supported - and tables are not part of that.

Furthermore, it appears that Hackage has the raw HTML option for rendering set to False, thereby quashing any hope one may have had of putting in a simple HTML table (which I think should also work in GitHub).

I think the best alternative (supported by both Hackage and GitHub) is just to put your table in a code block. That way, it is at least monospace font (so columns can align). That means you enter something like

```
| Header1 | Header2 | Header2 |
+---------+---------+---------+
| Cell1   | Cell2   | Cell3   |
+---------+---------+---------+
```

And it will render as

| Header1 | Header2 | Header2 |
+---------+---------+---------+
| Cell1   | Cell2   | Cell3   |
+---------+---------+---------+
Alec
  • 31,829
  • 7
  • 67
  • 114
  • Thanks for the well-researched answer! I have submitted [a request](https://github.com/haskell/hackage-server/issues/565) to support a larger subset of GitHub-flavored Markdown! – sjakobi Jan 13 '17 at 00:23
  • 1
    @sjakobi I reckon your best chance is probably if Hackage decides to enable inline HTML. Moving away from `cheapskate` would probably be a bad idea (it is fast and forgiving), and I think `cheapskate` won't be interested in adding non-standard features. – Alec Jan 13 '17 at 00:44
  • You may be right. I have opened [an issue](https://github.com/jgm/cheapskate/issues/18) for `cheapskate` anyway. – sjakobi Jan 13 '17 at 01:00