💡Github pages does not render README file correctly

[Incogdino]

As I was trying to set up GIthub Pages for my repo, I came across an issue where the README does not render properly on Github Pages. For example, this was what was produced when setting it up

According to Github Pages, it supports 2 markdown processors, kramdown and Github Flavoured Markdown (GFM)

Sadly for some reason that I do not know why, Github Pages uses kramdown. This can cause some formatting issue when the page is rendered. To solve this, you can follow this guide here.

Basically, you need to set up a _config.yml file under the /docs directory manually and specify the markdown processor

title: <title>
description: <description>
theme: <theme>
markdown: GFM

Even after setting this there are still some format that cannot be rendered properly. For example,

• Task lists don't work as expected
• Alerts also do not render properly (Image taken from here)

If anyone has any suggestions, please share them here. I'm also unsure if this should be labelled as a tip 😃

[Dinoman44]

Is it directly using the docs/README.md file from your repository? If it isn't, you may have typo-ed something. From the screenshot you shared, it seems like the table is entirely missing and there is just a closing </table> tag. That might be causing parsing issues and may be the reason your markdown is not being rendered.

If that still doesn't work, try to use pipe characters for your table instead of using the <table> tags. Here is how this works.

Basically just try to look for some inconsistency - unpaired brackets/backticks/tags, extra space etc.

[damithc]

@Incogdino Another thing: it will not be rendered properly if you don't separate markdown elements with a blank line.

Example A:

...
</table>
## Features
...

Example B:

...
</table>

## Features
...

Example A will not work but B will work. The blank line is required by proper Markdown but the lack of it is forgiven by GitHub Markdown preview. So Example A will work in the GitHub Markdown preview (giving the wrong impression that all is well) but will not work when it is rendered into an HTML page via GitHub pages.

[Incogdino]

@Incogdino Another thing: it will not be rendered properly if you don't separate markdown elements with a blank line.

Example A:

...
</table>
## Features
...

Example B:

...
</table>

## Features
...

Example A will not work but B will work. The blank line is required by proper Markdown but the lack of it is forgiven by GitHub Markdown preview. So Example A will work in the GitHub Markdown preview (giving the wrong impression that all is well) but will not work when it is rendered into an HTML page via GitHub pages.

Yup I made sure to include a newline in between but the error still persists

[Incogdino]

Is it directly using the docs/README.md file from your repository? If it isn't, you may have typo-ed something. From the screenshot you shared, it seems like the table is entirely missing and there is just a closing </table> tag. That might be causing parsing issues and may be the reason your markdown is not being rendered.

If that still doesn't work, try to use pipe characters for your table instead of using the <table> tags. Here is how this works.

Basically just try to look for some inconsistency - unpaired brackets/backticks/tags, extra space etc.

On hindsight, I should've included the whole screenshot of the table under the pile of text. But yea I did make sure to close the table with the appropriate tag. I also checked and made sure that there was only one closing tag so I'm not too sure why another closing tag occurred.

Anyways your suggestion of using pipe characters helped solve the issue. It also made the code look cleaner and less cluttered as compared to using HTML. Thanks for that!

Do you happen to know why some GFMD elements still cannot be processed like using task lists or alerts? Are there solutions out there for this too? I can't seem to find any.

[Dinoman44]

Glad I could help!

Unfortunately I'm not too sure why tasklists and alerts are not being processed since both kramdown and GFM support them (and with the same syntax, as far as I can tell). I'll keep looking, but if anyone else has figured out the solution feel free to jump in.