{"id":360,"date":"2017-04-28T09:58:55","date_gmt":"2017-04-28T13:58:55","guid":{"rendered":"https:\/\/mberlove.com\/blog\/?p=360"},"modified":"2017-04-28T09:58:55","modified_gmt":"2017-04-28T13:58:55","slug":"tricks-for-writing-readable-github-flavored-markdown","status":"publish","type":"post","link":"https:\/\/mberlove.com\/blog\/tricks-for-writing-readable-github-flavored-markdown\/","title":{"rendered":"Tricks for Writing Readable GitHub-Flavored MarkDown"},"content":{"rendered":"

John Gruber, the creator of MarkDown, has written<\/a>:<\/p>\n

For any markup that is not covered by Markdown\u2019s syntax, you simply use HTML itself.<\/p><\/blockquote>\n

 <\/p>\n

A lot of people seem to miss this important point, and the results are practically unreadable. Good MD isn’t pure MD; it’s styled and structured documents using MD to make the resulting plain-text as simple and uncluttered as possible.<\/p>\n

 <\/p>\n

GitHub-style MarkDown imposes additional restrictions on the kinds of tags, etc, you can use, which is probably a good thing, since it keeps things clean, spare, and visually uniform. Unfortunately, many people take this as an easy out, and write their MD docs in very lazy, unappealing ways.<\/p>\n

 <\/p>\n

If you want to make your documents readable, try a few of the following techniques — they’re really simple:<\/p>\n

 <\/p>\n

Line breaks<\/strong> and lots of them. A few <br \/>s at the end of your paragraphs doesn’t hurt plain-text readability, and it significantly<\/em> improves rendered readability.<\/p>\n

 <\/p>\n

Internal links<\/strong>, instead of one big page — this is absolutely supported by MD itself, so you have no excuse not to break down your content into comprehensible chunks.<\/p>\n

 <\/p>\n

Alt-text<\/strong>, also supported by MD, to improve accessibility and recognition by crawlers, etc.<\/p>\n

 <\/p>\n

Block-level elements like DIV<\/strong>, used sparingly, to give your document structure beyond headers.<\/p>\n

 <\/p>\n

HTML comments<\/strong>, to add meta “notes” to your MarkDown.<\/p>\n

 <\/p>\n","protected":false},"excerpt":{"rendered":"

John Gruber, the creator of MarkDown, has written: For any markup that is not covered by Markdown\u2019s syntax, you simply use HTML itself.   A lot of people seem to miss this important point, and the results are practically unreadable. […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[194],"tags":[207,205,206],"class_list":["post-360","post","type-post","status-publish","format-standard","hentry","category-communication","tag-github","tag-markdown","tag-writing"],"_links":{"self":[{"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/posts\/360","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/comments?post=360"}],"version-history":[{"count":3,"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/posts\/360\/revisions"}],"predecessor-version":[{"id":363,"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/posts\/360\/revisions\/363"}],"wp:attachment":[{"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/media?parent=360"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/categories?post=360"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mberlove.com\/blog\/wp-json\/wp\/v2\/tags?post=360"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}