Easier Dreamwidth Posts with Markdown: the sequel
Thursday, February 21st, 2019 04:32 pm![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
jesse_the_kRead 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
Markdown
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.
@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!