Mike's Introduction to Markdown

mike · 16 February 2022 01:34

One of the available syntaxes for Mojeek Discourse is Markdown.

You can find a quick reference for Markdown here:

CommonMark Reference

If your post has strange formatting that you want to get rid of, try escaping any symbols with backslash \

**Text in bold.** 

\*\*Text surrounded by asterisks.\*\*

Text in bold.

**Text surrounded by asterisks.**

Numbers might require a trailing period to be escaped.

1. Begin an ordered list. 

1\. A line that begins with the number one.

Begin an ordered list.

1. A line that begins with the number one.

Introduction

If you are not familiar with Markdown, it is a simple code you can include in your prose to add formatting.

From John Gruber:

Markdown allows you to write using an easy-to-read, easy-to-write plain text format …

… The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

In other words, if Markdown fails or you print the source code, Markdown can be read by humans.

Markdown retains relevant features from HTML (like links and lists), but it is much easier for humans to write and edit.

Examples

Here are some common examples of Markdown which I use.

Please see the References at the bottom of this post to learn more.

Inline Links

[Link text](http://example.com/)

Included as part of this pull is also an orientation quirk for the [GPD Win Max](https://www.mojeek.com/search?q=GPD+Win+Max).

Link text

Included as part of this pull is also an orientation quirk for the GPD Win Max.

Unordered Lists

* Item
* Item
* Item

Item
Item
Item

If you want to create a blank line within a list, use an HTML comment.

* Item
* Item
<!-- --> 
* Item

Item
Item

Item

Block Quotes

> A large grass fire in Wise County, Texas on Monday sent horses fleeing from the area, and led to some houses in the area being evacuated.

A large grass fire in Wise County, Texas on Monday sent horses fleeing from the area, and led to some houses in the area being evacuated.

Code Span

Use `Get-ChildItem` to list the contents of the current directory.

Use Get-ChildItem to list the contents of the current directory.

Code Block

```
<a href="https://www.w3schools.com">Visit W3Schools.com!</a>

```

<a href="https://www.w3schools.com">Visit W3Schools.com!</a>

It is possible to influence the syntax highlighting while using code fences. Note the missing color in this example.

```text
<a href="https://www.w3schools.com">Visit W3Schools.com!</a>

```

<a href="https://www.w3schools.com">Visit W3Schools.com!</a>

Headings

# HTML H1
## HTML H2
### HTML H3

HTML H1

HTML H2

HTML H3

Horizontal Rule

Before horizontal rule. 

---

After horizontal rule.

Before horizontal rule.

After horizontal rule.

Strikethrough

~~Strikethrough~~

~~Strikethrough~~

Image Etiquette

While it is possible to embed images in your post:

![Alternate text.](http://example.com/image.jpg)

I prefer to link to images:

[Link text](http://example.com/image.jpg)

This accomplishes several things:

Allows readers to choose whether or not they want to view an image.
Does not create rendering problems on smaller screens.
Saves bandwidth.

If you decide to embed an image, please fill in the alternate text which appears between the square brackets. For the visually impaired, this is all they know about your image. And this can be an aid to editors who might only have your source code.

Markdown Link Bookmarklet

If you want a convenient way to generate Markdown links from Web sites that you have visited in your Web browser, below, I’ve included a bookmarklet which will generate a link for you.

A bookmarklet is a small amount of JavaScript code that is saved in the address field of a standard, Web browser bookmark. This takes advantage of the JavaScript: scheme to run code against the current page. In our case, it allows a JavaScript prompt to pop up and display a link so that it can be copied:

Bookmarklet prompt showing a link formatted in Markdown.

Bookmarklet Code

To get started, just create a blank bookmark in your Web browser and paste the following code into the URL or address field in the bookmark’s properties. I typically use “Markdown Link” for the bookmark’s name.

javascript:(function(){
  var title = document.title; 
  var url = document.URL; 
  title = title.replace(/\u005b/g, "\\[");
  title = title.replace(/\u005d/g, "\\]");
  var myLink = "[" + title + "](" + url + ")"; 
  prompt("Markdown Link", myLink);
})();

In case you are wondering, the code is escaped with backslashes twice: once for JavaScript and once for Markdown. This allows page titles which contain [square brackets].

Bookmarklet Use

To use the bookmarklet, click on its bookmark. A prompt will appear with the link inside. Then, copy the link from your Web browser to your text editor. Close the prompt in your Web browser when you are done.

Note: This works for Firefox and Vivaldi. Other browsers might not allow bookmarklets to work.

Vivaldi Quirks

I noticed two quirks while using the bookmarklet in Vivaldi.

The browser address field will be updated to reflect the JavaScript code. This means, for example, if you run the bookmarklet and then unbookmark the page, you will be deleting the bookmarklet and not the bookmark for the current page. It also means that the page URL will no longer show in the address bar. To fix these issues either: 1) Refresh the page. 2) Right-click in the page body and choose the “Copy Page Address” option from the context menu.

Also, while the JavaScript prompt from the bookmarklet is showing, you won’t be able to interact with the page. Click the Cancel button to close the prompt before you continue using the page.

Showing Markdown

It is possible to demonstrate Markdown code while using Markdown.

You can display simple examples in code blocks:

```
*Italic*

```

You can demonstrate nested examples by switching between fenced and indented code blocks:

    ```
    *Italic*
    
    ```

References

* Learn more.

CommonMark Tutorial *

CommonMark Sandbox *

CommonMark Full Specification (Current) *

CommonMark Quick Reference

Discourse Features

CommonMark Home

Daring Fireball: Markdown

Supported Syntax Highlighting Languages | highlight.js (Latest)

HTML Headings | W3Schools

Bookmarklet | Wikipedia

URI Syntax | Wikipedia

Escape Character | JavaScript | W3Schools

Backslash Escapes | CommonMark Specification

Markdown Cheat Sheet | Markdown Guide

HTML comment tag | W3Schools

Changes

Creating an empty line in an unordered list.
Added Strikethrough
Fixed Bookmarklet Code

Created: Tuesday, February 15, 2022
Updated: Saturday, September 21, 2024

Josh · 16 February 2022 17:01

@mike, this is ridiculously useful, so much so that I’ve linked it in the on-boarding post to make sure it doesn’t get buried by other things to new users, thanks.

Colin · 17 February 2022 09:30

Thanks @mike . Concur with @Josh. I’ll be using your post as a reference when writing here and elsewhere - eg Joplin - a product we love.

mike · 17 February 2022 11:53

@Josh @Colin

Thank you.

I have my full draft saved locally. By default, new accounts are limited to two links. Here, I prioritized the quick reference and supported syntax highlighting languages. And the image was pulled in as content. It would be helpful if I could fill in the missing links. I can e-mail my draft to Aloe. Or I can update my post after my account is promoted. But I am not sure what the criteria for automatic promotion are.

Is there an explanation of the account ranks and criteria?

Kind regards,

PS

Also, I intentionally used headings for each section. If you hover to the left of each heading, you will find an auto-generated link. You can use that to directly link to the content you would like to reference.

Josh · 17 February 2022 12:37

The account levels aspect is something we haven’t changed really at all from stock, so you can find the explanation on the Discourse site here; I’ve bumped you up manually so that you don’t have to bother with fulfilling that criteria. We might take it down a notch or two as it’s quite a lot of hoops to jump through.

Kind regards back to you

mike · 17 February 2022 15:37

I tried to update my post. And I’ve sent an e-mail to Aloe explaining the situation. Let me know what you decide.

Josh · 17 February 2022 17:35

Thanks for sending it over @mike, from my end it looks like that did exactly what it needed to. It feels weird to overwrite someone’s comment, but it was just with your own content so not so bad a brilliant and comprehensive guide.

mike · 7 March 2022 04:24

If you’d like to type a URL without auto-linking:

mojeek.com

you can use a trick I picked up while working with WordPress.

If you encode text using HTML entities, the forum will not recognize it:

mojeek.com

Just keep in mind that editing the post later might cause the encoded text to devolve into plain text. Any plain text links within the editor would then auto-link after updating the post. This is why I tend to edit offline and paste into the forum. Doing so preserves an uncorrupted draft.

For encoding, I prefer to copy and paste out of mothereff.in There, just make sure to uncheck ‘only encode unsafe and non-ASCII characters’ to get fully encoded text. This is a suitable habit when frequently posting HTML.

However, if you want to make your life easier, you can just memorize the &period; entity which is enough to break the auto-link:

mojeek.com

Mike

mike · 5 November 2022 11:01

There is a bug with the bookmarklet. This version should work.

javascript:(function(){
  var title = document.title; 
  var url = document.URL; 
  title = title.replace(/\u005b/g, "\\[");
  title = title.replace(/\u005d/g, "\\]");
  var myLink = "[" + title + "](" + url + ")"; 
  prompt("Markdown Link", myLink);
})();