Markdown text for GitHub from HTML

Tricks to force Markdown to show things the way you want.

Overview

This post is about how to craft markdown text in a file like README.md.

This article adds real-world observations (PROTIPs) to the short introduction at guides.github.com/features/mastering-markdown.

Why Markdown?

Back in 2004, Apple pundit John Gruber came up with the idea of markdown after becoming frustrated by laborious HTML tags to properly format his content. [Wikipedia]

Markdown is a way to style text on the web by defining regular text with a few non-alphabetic characters.

Markdown is a simple writing system which makes web-based documents both easier to write and easier to read in their raw state.

GitHub renders markdown automatically in files with suffix of .md or .markdown, such as README.md or README.markdown.

Most technical people now write whole blog sites in Markup. This is largely to put docs nearer to code, usually in README files. Self-publishing sites such as GitBook make use of markup. Even fiction writers are writing in markdown code to use GitHub’s collaboration features.

Many non-technical writers prefer writing Markdown text instead of using the mouse-enabled Microsoft Word. They say writing pure text allows them to keep their fingers near the keyboard even as they apply formatting on the fly. Being able to format using text codes means they don’t have to stop typing or think about anything else to apply text styling.

markdownguide.org/basic-syntax displays how Markdown converts to HTML and output rendered by GitHub.

Alternatives to Markdown

In my opinion, Markdown is less limiting than crafting Confluence.

Alternative formats to Markdown include:

Automatic conversion

This article adds tricks to convert existing HTML into Markdown. I’ve had to convert hundreds of pages I’ve written in HTML since the 90’s.

You can copy HTML and paste into Dom Christie’s website for conversion to Markdown:

http://domchristie.github.io/to-markdown

Auto Convert HTML to text

The easiest way to convert HTML to Markdown text is to use Aaron Swartz’s

html2text.py Python script or on-line But it has not been updated since 2011.

My experience is that we’ll need to pretty much go through each line to make it look good in Markdown text.

Here’s a website that returns a page of Markdown text based on what you paste into it:

https://pandoc.org/try
Specify a URL in this website to convert the HTML page to text:

http://www.aaronsw.com/2002/html2text
Use this Python program to convert:

https://github.com/aaronsw/html2text

Download and run the program using this syntax (assuming Python is installed):
```
chmod a+x html2text.py ; ./html2text.py erlang.html
```

PROTIP: Automatic approaches today are usually too automatic, converting what is better left in HTML.

Paragraphs

One reason Markdown text is easier to write than HTML is there is no need for <p> to force a blank line.

Just a blank line will reflect as such in the output.

To convert from HTML with a lot of <p>, do a mass change (replace all) in a text editor.

Remember to clean up ending </p> tags by replacing them with nothing.

Markdown to HTML

To see your markdown turn into HTML, use the online tool at:

daringfireball.net/projects/markdown/dingus

Markdown recognizes up to 6 hash characters for 6 levels:

Heading (h2)

Sub-heading (h3)

Sub-sub-heading (h4)

Sub-sub-sub-heading (h5)

Sub-sub-sub-sub-heading (h6)

The headings above make use of ## (called Atx-style headers) instead of HTML <h2> tags.

## Heading (h2) #
### Sub-heading (h3) #
#### Sub-sub-heading (h4) #
##### Sub-sub-sub-heading (h5) #
###### Sub-sub-sub-sub-heading (h6) #

The ending ‘##’ character is optional, with any number of characters.

WARNING: Markdown is not good about indenting headings.

Alternately, Setext-style headers are specified (“underlined”) by a series of equal signs (for first-level headers) and dashes (for second-level headers):

First-level H1 headers
=============

Second-level H2 headers
-------------

Horizontal rule

A line going across the page accentuates divisions.

Use HTML markup tag:

<hr />

Ordered lists

My favorite feature of Markdown is it automatically ordered numbers in lists like this:

1. First item.
0. Second item.
9. Third item.

The coding above Markdown renders correctly as 1,2,3.

That means you can write this:

1. First item.
1. Second item.
1. Third item.
<br><br>

Indention

Markdown uses spaces in front of lines to indent text, such as:

1. First item:

   Something

2. Second item

CAUTION: No spaces in front of “Something” above would break automatic numbering. In order for numbering to continue, all lines must be indented at least 3 spaces.

Another good reason to let Markdown number for you is that after item number 10, you need to indent 4 spaces to avoid stopping auto-numbering.

Use 3 spaces in front of 3 backticks.

On their own, 4 or more back-ticks is a signal to highlight the sentence in a box, not to indent.

Not specified in most tutorials about indenting markdown is the use of a bug in HTML:

The <ul> HTML tag (meant to define an unordered list) around this text causes an identation of 4 spaces.

PROTIP: A workaround if you are not able to get automatic numbering: code the numbering yourself. To make Markdown interpret a paragraph starting with a number as a list, put a left-slash in front of the dot, as in:

1492\. That was the year.

Line breaks

PROTIP: Add line breaks (<br><br>) under lists so add a blank line before the next paragraph.

Both styles of line break tags result in a new line (without a blank line in between):

the XHTML style:

Hello<br />there

or HTML-style tags:

Hello<br>there

Unordered Lists

CAUTION: Even though HTML can be written or pasted into markdown (.md) files, HTML must be more correct in Markdown than HTML read by internet browsers.

There must be a blank line before <ul> or <ol>.
For every <li> there needs to be a </li> or the rendering goes wacky.
There must be a blank line after anchor tags <a name=... and a heading text line.

WARNING: Markdown may not recognize different characters to parse into lists:

* Asterisk

+ plus sign

- minus sign

render as:

Asterisk
plus sign
minus sign

Special characters

Markdown treats these characters as ordinary text if there is backslash escape character in front of them:

\\ backslash itself
\` backtick
\* asterisk
\_ underscore
\{ \} curly braces
\[ \] square brackets
\( \) parentheses
\# hash mark
\+ plus sign
\- minus sign (hyphen)
\. dot
\! exclamation mark

PROTIP: If a URL contains attributes, convert & (ampersand)

Another aspect where it would be helpful to use tools is conversion of some special characters that Markdown converts into escape entities that begin with an & (ampersand),

< (less than) is turned into <
> (greater than) is turned into > because that’s used to signify block quotes in Markdown.
the ampersand itself turns to &, as in link URLs.

Tables in HTML

Some early websites used HTML table code to format an entire page. Such coding would need surgery to look well since tables are now intended to fit into a text column. But HTML table coding in Markdown document usually renders well:

Column 1	#
Here and there	1,234,567
Everywhere	2
Sum:	1,234,569

is rendered by this code:

<table border="1" cellpadding="4" cellspacing="0">
<thead><tr><th align="left">Column 1</th><th align="right">#</th></tr></thead>
<tbody>
<tr valign="top"><td>*Here* and<br><strong>there</strong></td><td align="right">1,234,567</td></tr>
<tr valign="top"><td>Everywhere</td><td align="right">2</td></tr>
</tbody>
<tfoot><tr valign="top"><td align="right">Sum:</td><td align="right">1,234,569</td></tr>
</tfoot>
</table>

In headings, center alignment is the default, so align left is necessary.

valign (vertical alignment) is necessary to keep text at the top of boxes rather than centered vertically.

Bold and italics in Tables

CAUTION: GitHub Markdown coding is not processed within HTML tables. (The “Markdown Extra” does though)

Within the sample table above, asterisks in *Here* are normally recognized as Markdown code to bold.

So within HTML table code use HTML coding:

<strong>emphasized</strong> rather than Markdown __emphasized__ or **emphasized**

which renders the same:

emphasized rather than Markdown emphasized or emphasized

Continue to italicize with:

<em>italicized</em> rather than Markdown _italicized_ or *italicized*

which renders the same:

italicized rather than Markdown italicized or italicized

Links

PROTIP: Keep coding HTML to link to external sites and images.

Example of HTML:

<a taget="_blank" title="hello" href="http://wilsonmar.github.io/">my site</a>

The biggest hassle with converting to Markdown text from HTML coding is that Markdown reverses the order of text and links.

 [mysite](http://wilsonmar.github.io/)

The same goes for the alternate “automatic” format Markdown offers to link:

<http://wilsonmar.github.io>

I’m reluctant to put external links in Markdown because they open in the same window, causing my site to lose visitors to that site.

![mysite logo](http://wilsonmar.github.io/favicon.png/ "optional title")

Notice that links to images would have an exclaimation point in front.

Markdown currently has no syntax for specifying the dimensions of an image.

To embed a YouTube video, use an HTML iframe.

<iframe width="560" height="315" src="https://www.youtube.com/embed/Onv9nhPIBp0" frameborder="0" allowfullscreen> </iframe>

To specify starting the video at a specific time (1 minute 2 seconds), use a link such as:

<a target="_blank" href="https://www.youtube.com/watch?v=Onv9nhPIBp0&t=1m2s">Link to YouTube</a>.

Click to expand

Click to expand!

Hidden text

Click on the “Click to expand!” above to reveal hidden text.

To hide text until the reader clicks, surround the hidden text this way:

&#123;details>
  &#123;summary>Click to expand!</summary>
Hidden text
&#123;/details>

Blockquotes in HTML

Markdown ignores the HTML <blockquote> tag. So this appear as if it was not surrounded by the tag:

<block>
This is a block quote.
</block>

Different Parsers

The trouble with Markdown code is that different parsers render them differently into HTML.

In March, 2016 GitHub switched to the Kramdown parser which claims to incorporate the capabilities of other parsers:

Liquid Markdown Syntax

Markdown text in GitHub recognizes Liquid syntax as defined in:

[https://docs.shopify.com/themes/liquid/basics](https://docs.shopify.com/themes/liquid/basics)

This coding would process html as such between a set of Liquid {% tag markers:


{% highlight html %}
Hello
{% endhighlight %}

Liquid output markup can also be specified between two curly braces, such as:

{{ page.heading | upcase | truncate: 8 }}

The page.heading refers to the heading variable specified in the front matter at the top of the file.

To display Liquid markup in documentation:


{% highlight html %}{% raw %}
{{ page.heading | upcase | truncate: 8 }}
{% endraw %}{% endhighlight %}

In fact, Liquid is a rather (simple yet complete) programming language on its own right, with if/then/else, for loops, etc. The home page for Liquid template language (written in Ruby):

shopify.github.io/liquid/

JavaScript

What if we pasted JavaScript (wrapped between <script> tags) in Markdown?

Footnotes

This incorporates the thorough detail about markdown coding at:

daringfireball.net

A discussion forum about markdown is at:

pairlist6.pair.net/mailman/listinfo/markdown-discuss

References

whatismarkdown.com
List of markdown editors across operating systems
https://blog.ghost.org/markdown
Markdown to Ebook is available on Leanpub.com, about how to write a book in Leanpub using Markdown.
Jeff Geerling’s musings on writing a book

More on front-end styling

This is one of several topics:

More about Git & GitHub

This is one of a series on Git and GitHub:

Wilson Mar