Switch from Redcarpet to Kramdown as markdown engine
What
Switch the markdown engine used for docs.gitlab.com from redcarpet to kramdown
Closes https://gitlab.com/gitlab-com/gitlab-docs/issues/50 https://gitlab.com/gitlab-com/gitlab-docs/issues/239
Why
Kramdowm is the most featured markdown engine, which we use for about.gitlab.com for more than a year.
With it, we will have the ability to:
- add custom styles to docs, e.g. blue and green info bars on GH docs
- HTML will not be escaped, so we can add icons, divs, videos, iframes, etc
- we will be able to add custom styles to docs, e.g., display images side-by-side
- add custom ids and custom classes with kramdown markup
{: #id .class}
See all the awesome stuff we can do with kramdown here in our markdown guide.
Kramdown is the engine recommended by Nanoc
How
As we are introducing frontmatter to our docs, although it's not supported by /help, I suggest we also add kramdown as markdown engine. It will not be rendered by /help, but will significantly improve the quality of our docs visual, design, and readability.
A gem will be used that will port GitLab's markdown to kramdown https://gitlab.com/brodock/gitlab_kramdown.
Todos
-
ToC with redcarpet is generated automatically, with kramdown we need different solution -
Javascript needs to be fixed to work with kramdown's ToC -
Anchor links do not work (no #beside them that could be used to easily select them) -
Port all the custom stuff defined in /lib/helpers_.rb -
ToC must be configurable via Frontmatter -
Figure out why the "Edit this page" on bottom of page is not showing up -
ToC links style is lacking one "space" between list symbol in level 3 in kramdown version (CSS) -
Include Rel Canonical tag -
Handle anchors of duplicate titles https://gitlab.com/gitlab-com/gitlab-docs/issues/239 -
Mermaid support https://gitlab.com/gitlab-com/gitlab-docs/issues/151