Easy Markdown Editing Without List Styling Worries

Discovering Markdown's Unique Specification

Recently, while working extensively with Markdown, I stumbled upon a peculiar aspect of its specification. It's unclear whether this is part of the original Markdown spec or emerged with CommonMark. Regardless, it's significant since most Markdown converters behave this way.

The List Formatting Dilemma in Markdown

In Markdown, we often use bullet or numbered lists, which are incredibly handy. However, the spacing within these lists can vary - sometimes the spacing widens, or in other cases, it becomes narrower. This variation is mainly due to differences in the spacing before and after paragraphs.

Resolving List Inconsistencies

A common approach is to insert blank lines before and after bullet lists, which ensures consistent spacing. However, this can vary based on the content. For instance, in coding standards documents (like those on GitHub or hosted on our website using Jekyll), we often space out each item for clarity, especially when dealing with lengthy sentences.

Markdown to HTML: Tight vs. Loose Lists

When converting Markdown to HTML, lists are categorized as either 'tight' or 'loose.' Lists become 'loose' when interspersed with blank lines and 'tight' otherwise. In HTML, this difference is represented by the presence (or absence) of <p> tags next to the <li> tags.

The Challenge with Sub-Lists

One limitation is controlling the spacing in sub-lists, especially when there's only one item. Standard Markdown doesn't support this well, and it often requires unconventional solutions.

Markdown's Overreach into Document Styling

A critical observation about Markdown is its unintended role in document styling, which ideally should be managed by CSS in HTML. This overreach suggests that certain aspects of Markdown standards might be better off discarded.

POCU's Approach to Markdown

In our company, we've adopted a practical approach: format the Markdown documents in whatever way is most comfortable for the writer, without worrying about tight or loose lists. When these documents are published on websites or blogs, the contained Markdown gets converted to HTML and placed within a <div> section. This allows us to standardize the appearance of lists using CSS, effectively removing any distinction between tight and loose lists.

Conclusion

In summary, Markdown's list formatting can result in either 'loose' or 'tight' lists, influenced by the insertion of blank lines. However, for ease of writing and consistency in presentation, it's advisable to focus on content and leave styling to CSS in the web environment. This approach has greatly simplified our documentation process and could be beneficial for others as well.