@azah welcome and congrulations on your first pull request 🎉

Updated, because apparently table.align is deprecated.

At first I was thinking that this just GFM and doesn't need to be part of the Crystal markdown parser but seeing as...

1. Many project READMEs will be in a Github repo
2. The first page for a Crystal project doc will use the same README

...then we should support it just for the sake of crystal docs

This actually breaks for all of the examples on Github's page about tables

require "markdown"

md = "

# MyProject

## A Table

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

"

Markdown.to_html md
# Missing hash key: 0 (KeyError)

And I would add some more tests. I would test against the examples on that Github page I shared and also the Ruby Kramdown lib actually has a good collection of markdown text files and the expected HTML output.

@samueleaton yeah I now realize github doesn't support the format I used, it appears they require the --- line to delineate between header / data cells. At the time I was just developing it for my own personal use.

I would have to rewrite the code then pretty much, so I will at some point.

Not sure we should support this, CommonMark only allows the HTML syntax, see http://spec.commonmark.org/0.27/ rule 4.6.6.

@jhass well, GitHub flavoured markdown has supported PHP markdown tables for a while. Redcarpet and friends deal with this by being able to turn on or off unofficial extensions.

I'd say that the best way to do this is to conform to commonmark by default but allow extensions to the markdown parser. This would probably require the markdown code to be rewritten to allow extensibility however.

CommonMark has no table support at all besides using raw html, which is both ugly and tedious compared to markdown's simplicity.

Kramdown, Github, Gitlab, and PHP Markdown Extra use this format for tables:

| header 1 | header 2 |
| -------- | -------- |
| cell 1   | cell 2   |
| cell 3   | cell 4   |

with left, center, or right alignment syntax as follows:

| Left | Center | Right |
| :--- | :---: | ---: |

They also also support this syntax:

header 1 | header 2
-------- | --------
cell 1   | cell 2
cell 3   | cell 4

I think that we use tables enough that they should be a core aspect, and we definitely use Github/Gitlab enough to give their syntax merit.

However, extensions would be a good idea, because of differences like Gitlab's emojis or diff syntax:

{+ additions +}
[+ additions +]
{- deletions -}
[- deletions -]

References:

• CommonMark discussion on table syntax
• Github Markdown
• GitLab Markdown
• Kramdown - based on PHP Markdown Extra
• PHP Markdown Extra

Maybe this can be a standalone shards for parsing more markdown dialects?

That's likely the best solution because custom extensions like {+ additions +} are useless without a parser that can understand it.

Unfortunately I am working full time as a teacher & studying Korean- if someone else is interested in working on this by all means go ahead. I'll eventually make a shard at some point in the future.

Crystal should support GFM by default because it's standard de facto. And it's great for API documentation etc.

Just look at https://toolchain.gitbook.com/syntax/markdown.html

Please keep the discussion about improving the markdown implementation in #4613