Inconsistency between GitHub file preview and GitHub Page
Closed this issue · 2 comments
When displaying tables, certain tables that can be displayed properly in markdown will appear to be jumbled when viewed in the github pages.
One of such examples can be seen in this issue.
test
| Action | Format | Examples |
|:--------------------|:----------------------------------------------------:|------------------------------------------------:|
| List tasks | list | list |
| Add a todo task | todo [task name] | todo task |
| Add a deadline task | deadline [task name] /by [deadline date] | deadline task /by 2023-2-14 |
| Add an event | event [event name] /from [start date] /to [end date] | event recess week /from 2023-2-20 /to 2023-2-26 |
| Find a task | find [keyword 1] ... | find recess 2022 |
| delete a task | delete [index] | delete 10 |
renders to
The reason why it is rendered as such is seen in the following comment
The fix is as described in the issue which is to replace kramdown with GFM (Github flavoured markdown) to ensure consistent rendering.
I have noticed a compatibility issue when switching over to GFM,
AB3's documentations uses Kramdown's {:toc} tag to automatically generate table of contents which is not included in GFM. This causes the Table of content to fail to render. So it might be unwise to switch over to GFM from kramdown.
It might be possible to resolve this by including 3rd party libraries, but it might be an overkill at that point.
Alternatively, we can choose to include a manual ToC or some script to generate the markdown for the ToC if the value of consistent table rendering outweighs this feature.
The main difference is that kramdown requires a line spacing between tables and text prior, so for the above example, by including a new line between the table and "test"
like so
test
<-- new line -->
| Action | Format | Examples |
|:--------------------|:----------------------------------------------------:|---------------------------
The table will be successfully rendered with kramdown
@Eclipse-Dominator Good catch. Yes, in that case it is better to leave it as is.