TechPrufer
Sign inGet started

Blogs›GitLab›Markdown Rendering and Flavored Markdown

Markdown Rendering and Flavored Markdown

Markdown Rendering and Flavored Markdown

5
posts
2014–2019

GitLab's approach to rendering Markdown has evolved to align with established specifications, particularly concerning newline behavior. Initially, GitLab rendered all line breaks. The platform then proposed and implemented changes to conform to the Markdown specification, requiring two spaces at the end of a line for a line break, while paragraphs remain separated by blank lines. This change was applied consistently across all Markdown rendering within GitLab, including issue and merge request descriptions and comments, to ensure a uniform user experience. This post details the debate and technical considerations around line wrapping in documentation and user-generated content, highlighting the trade-offs between authoring ease and review readability, and proposing potential UI solutions to mitigate the challenges.

2019

How we migrated to CommonMark

6/13/2019

This post details GitLab's migration from RedCarpet to CommonMark for Markdown rendering. It outlines the motivation for the migration, focusing on the inconsistencies of various Markdown flavors and the goal of achieving consistent rendering across platforms. The migration was executed in three phases: initially only for new content, then extending to repository and wiki files, and finally removing RedCarpet entirely. The post also highlights improvements made upstream to the cmark-gfm library, specifically regarding strikethrough syntax and a bug fix for table rendering. A tool, diff_redcarpet_cmark, was developed to assist in converting existing content.

2018

A 5-minute Markdown tutorial

8/17/2018

This post introduces GitLab Flavored Markdown (GFM) and its specific features like referencing issues, commits, merge requests, or team members; autolinking URLs; creating diagrams and flowcharts using Mermaid; and quick actions. It also provides a basic Markdown tutorial and discusses the benefits and ways to get started with Markdown.

2016

To Wrap or Not to Wrap: One of Life's Greatest Questions

10/11/2016

This post details the ongoing debate within GitLab regarding line wrapping in documentation and user-generated content. It presents two opposing views: 'don't wrap it' (relying on reviewers to wrap text locally) and 'do wrap it' (wrapping text to prevent horizontal scrolling for reviewers and editors). The post illustrates the visual differences and challenges of each approach with screenshots and discusses potential future solutions like setting max-width for comment boxes and editors. It also clarifies the current style guide policy and the preference for wrapped text in blog posts to facilitate review.

Markdown Kramdown Tips and Tricks

7/19/2016

This post details how to leverage Kramdown's syntax for applying CSS classes, custom IDs, and attributes to elements, generating tables of contents, embedding HTML blocks (including iframes and CodePens), and mixing HTML with Markdown. It also covers the ability to add `<style>` tags directly within markdown files for localized styling. The post emphasizes the flexibility and power of Kramdown for creating rich content within the GitLab platform.

2014

Markdown newline behaviour

2/21/2014

This post proposes a change to GitLab's Markdown rendering to align with the official Markdown specification, specifically regarding newline behavior. It advocates for rendering line breaks only when a line ends with two or more spaces, while paragraphs remain separated by blank lines. The post also highlights that this change will be applied uniformly across all Markdown usage within GitLab, including issues and merge requests, to maintain a consistent GitLab Flavored Markdown experience.