Easier Dreamwidth Posts with Markdown: the sequel

[jesse_the_k]

Read Markdown Simplifies Formatting Your DW Posts for an introduction and the formats you'll use daily.

This sequel covers the rest of Dreamwidth’s Markdown support.

• Paragraphs and line breaks
• Blockquotes
• Headings
• Reference links
• Images
• Ignoring Markdown commands

By design, Markdown includes HTML—you can include any HTML code and entities in your Markdown without special handling.

You use Markdown when composing entries on the web or in email, by making your first line !markdown. It’s on by default when you reply by email. You can’t use Markdown when replying to comments on the Dreamwidth website.

Paragraphs and line breaks

Two Returns become a paragraph—in HTML terms, it's a <p>. Two Returns create the blank line required for the start and end of Markdown-format lists.

Two spaces then a Return creates a line break in Markdown. That's <br> or <br /> in HTML. Use line breaks for poetry and songs. You can use line breaks in lists to create subsidiary paragraphs after the list item (a visual approximation of <dt><dd> lists).

---

Blockquotes

Begin every quoted paragraph with > greater-than space. Blank line turns off block quote. To include more than one paragraph in the block quote, you must also begin the blank lines with >

Markdown

> Now once again, where does it rain?
>
> On the plain! On the plain!
>
> And where's that blasted plain?

Displays as

Now once again, where does it rain?

On the plain! On the plain!

And where's that blasted plain?

Markdown

> Now once again, where does it rain?

On the plain! On the plain!

> And where's that blasted plain?

Displays as

Now once again, where does it rain?

On the plain! On the plain!

And where's that blasted plain?

Journal style determines how block quotes display. [Turn on my style to see text indented in a light blue square, with dark blue rules above and below.] ETA 6/19 changed my journal style, made this concept useless.

---

Headings

Markdown supports five levels of headings: 1 at the top to 5 at the bottom. Level one starts with # hashtag space. Each lower level adds one hashtag. Level 5 begins with five # hashtags and a space. Use a blank line or line break after. Journal style determines heading appearance, including choice of font, size, spacing between letters and paragraphs.

Markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5

Display as

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

---

Reference Links

The Reference Link syntax is similar to a footnote. It's helpful

• to focus on your writing
• to keep your prose free of link clutter
• to maintain correct format when emailing Dreamwidth (some email programs will insert a line break after a closing bracket)

The Reference Link has three parts:

• the anchor text
• a reference ID you define
• the full URL link address

The syntax is:

[anchor text within square brackets][reference ID in square brackets]

then any place later in the text

[reference ID in square brackets]: full URL

You must have a colon, and may have a space, between the reference ID close square bracket and URL.

Choose a reference ID that's easy to remember and type. I group all my links at the end of the post I'm drafting. This minimizes internet rabbit-holes by bundling link-checking into one task, and also simplifies updating the post when links rot.

You can also use an empty reference ID, where the anchor text becomes its own reference. For example, [Google][] followed by [Google]: https://www.google.com.

My first Markdown post introduced the other two ways to show links: inline and bare.

[inline anchor text in brackets](URL in parentheses)

<example.com> URL enclosed in <> for clickable bare link

---

Images

Markdown forces you to define alt text with this syntax

![alt text](full link to image "optional image title")

Markdown

![Oak tree base adorned with three clusters of fungi](https://mltshp-cdn.com/r/1FKQM "Fungi Cornucopia")

Displays as

Based on my tests, this image automagically scales to the browser window, so it’s an improvement on the default DW insert HTML, which needs a width="100%" in it

---

Ignoring Markdown Commands

Precede any Markdown command with \ backslash to turn off its power and display it. (Coders call what the backslash does an "escape character".)

Markdown

\_tiny-fan_ and \**kisses**

My handle is \@jesse_the_k

\##### hashtags were once octothorpes

Display as

_tiny-fan_ and **kisses**

My handle is @jesse_the_k

##### hashtags were once octothorpes

Without the backslash, it would display as

tiny-fan and kisses

My handle is jesse_the_k

hashtags were once octothorpes

---

Markdown Simplifies Writing About HTML

Markdown automatically escapes HTML inside the backtick pairs which mean sample code. I can write `<this> & <that>` without any entity references.

---

Markdown Ecosystem and Tools

John Gruber, inspired by Aaron Swartz and many others, defined Markdown 1.0.1 in 2004.
https://daringfireball.net/projects/markdown/syntax

Dreamwidth supports this specification, which is coded in DW's mother tongue, Perl.

Dreamwidth also provides "at" shortcuts. When you use these shortcuts the correct icons display for the site, but they don’t alert the user.

@account for local usernames
@username.site for users on other sites.

---

Markdown isn't standardized, unlike HTML or CSS. It is popular--you can use Markdown on many modern sites, including Reddit, Discourse, Discord, Tumblr, and Wordpress. Since 2004, people have created numerous "flavor" variations; Babelmark compares their features:

• Github-Flavored Markdown (GFM)
  https://github.github.com/gfm/

• Commonmark
  https://commonmark.org/

• Critic Markup
  http://criticmarkup.com/

• MultiMarkDown (MMD)
  https://fletcherpenney.net/multimarkdown/

Without standardization, you can’t predict exactly how Markdown will work between applications (whether that's a text area on the web or an editing app on mobile/desktop). Since the flavor innovators are mostly programmers working with extensible text editors, it's easy for them to improve Markdown as they go.

(I used line breaks in this unordered list to keep the flavor name and links together under one bullet.)

Markdown-Aware Editors

Most Markdown applications offer features beyond the original Gruber spec which Dreamwidth supports. When you use a Markdown-aware editor, assume that Dreamwidth won't implement every feature. The good news is you can still compose and preview your entry in the Markdown-aware editor. When it’s ready, copy the HTML version into a Dreamwidth post. When you do this, add <raw-code> at the top to suppress extra spaces between paragraphs.

Online Markdown Editors These tools run in your browser window. They can read and write files to local drives or your browser memory:

StackEdit offers toolbar and keyboard shortcuts (update 18Mar 19: now offers cloud drive support)

Dillinger can read and write from cloud drives, no toolbar or keyboard shortcuts

Check your browser’s extension store for helpful tools that can copy a page selection and title to Markdown with a click.

Online resources

Hands-on learning at https://www.markdowntutorial.com/

A complete syntax for all the flavors is hosted by Marc Cone at https://www.markdownguide.org. He’s compiled that site into a free ebook as well.

Desktop and mobile editors

Brett Terpstra hosts an extensive list of Markdown software tools for Apple products. Most programming editors now provide Markdown input and preview. GitHub offers Atom.io for free on Mac, Windows, and Linux.

There are scores of Markdown editors aimed at prose writers. They use Markdown's simplicity to help you focus on actually writing, instead of fiddling with formats. I've been using iA Writer (Mac, iPad, Windows, Android) for several years. Feel free to recommend your tools in comments!

Comments

[sqbr]

Ooh thank you for this!

[jesse_the_k]

My very great pleasure

[replyhazy]

You are a Friend to Posters.

[jesse_the_k]

Me and Blutack!

[kate_nepveu]

Thank you!

Note: IME markdown is _not_ automatically on for email posting, just email comment replies.

[jesse_the_k]

Thank you for catching this error.

[mdlbear]

Very cool! emacs and vim also have good support for markdown.

Expect a writeup of my git+make toolchain not too long from now. Although I'll have to resist the temptation to tweak it first -- the fact that emacs has different key bindings in Markdown and HTML modes is maddening, and my toolchain doesn't support @user -- yet.

Excellent to know

[jesse_the_k]

...that emacs and vim are futureproof.

Re: Excellent to know

[mdlbear]

Yup. Also, one can use Pandoc to convert different flavors of markdown to HTML (or other flavors of markdown!); I'm using it for git-flavored markdown.

[silversandbea]

Thanks for the intro! I'm going to try to play around with this over the weekend.

[ljwrites]

Another great post! I've found posting a lot easier and simpler since I learned Markdown from your earlier post, and this post expands the lesson in useful ways. I have to admit, I was excited at the reference link because I thought they put actual footnotes in the post 😂 but I can see its use and look forward to using it in posting.

So happy to be an MD enabler.

[jesse_the_k]

Actual footnotes would be awesome--that's one thing that iA Writer supports in Markdown but its HTML output is terrible (for some reason it puts <p>s between the footnote number and the body).

Re: So happy to be an MD enabler.

[ljwrites]

Wth, who wants footnote text on a separate paragraph from the number? XD It would be awesome to be able to customize HTML output.

And I did end up loving the reference link function--the link getting out of the immediate text is an absolute godsend and re-using links in the same post, should I want to do so, is a snap!

[illariy]

Here via star_anise. Very useful post! Have put it into Memories.

[brewsternorth]

Thank you thank you!

[duskpeterson]

Thank you so much! I started using markdown at DW after I saw your earlier post, and this post answers some of the questions that had arisen in my mind.