mattcone / markdown-guide

The comprehensive Markdown reference guide.

Markdown Guide

The Markdown Guide is a comprehensive Markdown reference designed for both novices and experts. It was born out of frustration with existing Markdown references that are incomplete and inadequate.

Contributing

Contributions are welcome. Feel free to open a pull request with changes.

Running it Locally

It can be helpful to preview changes on your computer before opening a pull request. The Markdown Guide uses the Jekyll static site generator. After forking or cloning the repository, perform the following steps to generate the site and preview it:

• Make sure you have ruby installed on your computer. See https://www.ruby-lang.org/en/downloads/
• bundle install
• bundle exec jekyll serve
• Point your browser at http://127.0.0.1:4000/

Adding tools

See this page for information about adding applications to the Markdown tools directory.

License

The content of this project itself is licensed under the Creative Commons Attribution-ShareAlike 4.0 International license, and the underlying source code used to format and display that content is licensed under the MIT license.

markdown-guide's Issues

Barcelona people speak Catalan

People in Ciudad Juárez speak Spanish just like the people in Barcelona, but there are substantial differences between the dialects used in both cities.

So my wife speaks Spanish natively (she's from Mexico City). We went to Barcelona. All the signs were in Catalan. Spanish was not the first language they spoke, and some people would not speak Spanish (they call it Castilian in Spain).

The region of Catalonia has two official languages. Spanish and Catalan, of which are both spoken. In offices and schools, Catalan is the dominant language.

Barcelona's languages

I would consider changing to maybe British English vs American English or Southern USA vs Northern USA in future revisions.

Just my 2 cents.

Update to tools

Thanks for this great resource!

Here are a few additional Markdown tools:

Zettlr: https://www.zettlr.com/

Byword: https://bywordapp.com/

nvALT: https://brettterpstra.com/projects/nvalt/
nvUltra (replacement to nvALT): https://nvultra.com/

Wikilink inconsistencies

The "Tools" pages for BatNoter, Bear, Dendron, GitJournal, Obsidian & Wiki.js all mention support for [[note-name]] internal links, also referred to as "Wikilinks" or "Wiki style links", but the way this support is shown varies.

It would be nice if the way this support is shown -- and the nomenclature used -- was consistent.

Below is a summary, in alphabetical order.

Support for Additional Syntax Elements

As an added bonus, BatNoter provides support for several obscure elements.

Element	Markdown	Rendered Output
WikiLinks	[[PageName]]	Links to the file PageName.md

-- _tools/batnoter.md#L71-L90

notes: "You can link to other notes by enclosing a note's name in double brackets (i.e., [[note-name]])."

-- _tools/bear.md#L33

notes: "You can link to other notes in Dendron by using the [[Link name|filename]] syntax."

-- dendron.md#L30

GitJournal additionally lets you easily link your notes together with a Wiki style link - [[FileName]]. This lets you easily interlink different ideas and even build your own knowledge base.

-- _tools/gitjournal.md#L73

Support for Additional Syntax Elements

As an added bonus, GitJournal provides support for several obscure elements.

Element	Markdown	Rendered Output
WikiLinks	[[PageName]]	Links to the file PageName.md

-- _tools/gitjournal.md#L77-L96

notes: "You can link to other notes in Obsidian by using the [[file name]] syntax."

-- _tools/obsidian.md#L30

notes: "You can link to other notes in Dendron by using the [[Link name|filename]] syntax."

-- _tools/wiki-js.md#L31

Issue with Discord docs

Discord has support of links, but only in certain cases.

Links do work in embeds (in fields where markdown works), and in webhook messages/slash commands

Getting Started: Tweak the content for beginners

"Getting started. What is Markdown?" is a great, useful section that has been carefully written for people completely new to markdown. However the focus is on the "Format, and not the File". I suggest a small tweak for clarity.

Explanation:
Some places require a markdown file. And, sensibly, refer newbies to the Markdown Guide. Many people know MS Word and MS Word files, and typically assume that Markdown files need the Markdown application. They have never seen or know the existence of plain text files.

My suggestion:
Explain that a special Markdown application is not required. And explain briefly what a plain text file is.

Paragraph 4 Before:
You can add Markdown formatting elements to a plaintext file using a text editor application. Or you can use one of the many Markdown applications for macOS, Windows, Linux, iOS, and Android operating systems.
Paragraph 4 After (suggestion):
Markdown text is stored in a normal text file. The sort of file created with any text editor application such as Notepad. And can have any file name extension such as .txt or .md. The file contains only plain text, including the Markdown formatting elements. You can use one of the many Markdown applications for macOS, Windows, Linux, iOS, and Android operating systems. But no dedicated application is needed.

(But maybe there way to express it better than my suggestion.)

Issue with Notion docs

    my codes

this not support

Add Standard Notes to Notes p 9 -10

Hi Matt,
Your book is great - just bought and downloaded it.

I wonder if you know about Standard Notes. It is privacy-protecting and has a number of markdown editors you can select as your template. I want to recommend adding it to the Notes chapter. I migrated from Evernote to Standard Notes a few years ago. It's a good experience.
All the best!

Enumerated lists don't need to start with 1, however...

In the Markdown Guide, I noticed this statement:

The numbers don’t have to be in numerical order, but the list should start with the number one.

However Gruber's original syntax guide at Daring Fireball specifically says:

The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that
the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't have to.

The emphasis here in both cases is mine and is key to the part that I struggle with. A numbered list in Markdown does not have to start with the number one, it just makes sense to do it that way because of how processors mangle markup languages. So somehow, the statement needs a little clarification.

This is the crux of it:

There's this whole topic of lightweight markup language processing that isn't really the point of this guide. Processors take your markup and make everything suitable for display on a web page by translating it into a real document markup language like HTML. That's why your markup is only considered "lightweight." Once server software converts your text and its markup so that it can be displayed, your stuff will break in weird ways if you don't start your enumerated lists with 1.

I'm struggling with how to add all add that to this guide and still maintain the simplicity.

Issue with MacDown

Received message that macdown file was corrupted and could not be run.
Installed from both Homebrew and downloaded zip file.
Macbook Air
Mac OS Mojave 10.14.5

Issue with Markdown Here docs

_tools/wiki-js.md: "Dendron" typo

notes: "You can link to other notes in Dendron by using the [[Link name|filename]] syntax."

-- https://github.com/mattcone/markdown-guide/blob/master/_tools/wiki-js.md?plain=1#L31

Issue with MacDown docs

I get " “MacDown” cannot be opened because the developer cannot be verified." When trying to install

Trying to install in my iMAC and I get the above message ??

Issue with Todoist docs

Hi there,

I don't believe table formatting works anymore in the comments section of Todoist tasks.

(I'm on Windows, in Chrome, on the Todoist WebApp)

Cheers, and thanks for your great documentation!

Duplicate class attribute on tag

Hi, I'm using https://dillinger.io/ to convert markdown to html, but I see we have duplicate class attribute on tag, example:

• markdown code

#include "EzyHeaders.h"

I got:

<pre><code class="has-line-data" data-line-start="1" data-line-end="3" class="language-cpp"><span class="hljs-preprocessor">#<span class="hljs-keyword">include</span> <span class="hljs-string">"EzyHeaders.h"</span></span>
</code></pre>

Issue with MacDown docs

tools/logseq: "footnotes : no" is out of date

I've verified footnote support in the version I'm using, 0.8.15, but seems it has been supported since about October 2021 / Logseq 0.4.4.

Interpretation of nested emphasis

The CommonMark spec says that when nesting bold and italic:

An interpretation <em><strong>...</strong></em> is always preferred to <strong><em>...</em></strong>.

However your examples have it the other way round.

Note this was a change in version 0.28 (2017) of the spec. Earlier versions had it the other way round.

gently emphasize _with a colon_ in the footnote anchor docs?

Hi, I've spent quite some time thinking footnotes don't work until I realized the colon : is really important :-D (footnote anchor docs)[https://github.com/mattcone/markdown-guide/blob/92783240a94f29caafbdc31a75b3b97f563cde3a/_extended-syntax/footnotes.md?plain=1#L14]

maybe emphasize "with a colon" : visually, somehow?

cheat-sheet.md Preview Problems

Hi, line 115 in cheat-sheet.md breaks markdown preview on GitHub and in other Markdown previewers. Deleting the line fixes the problem. Would like to make a pull request if you think it's worth fixing. Thank you.

Issue with Notion docs (highly opinionated but still :D )

I honestly feel that you cannot change the rules of how to write markdown. Please do not "reinvent" things.

notion

• toggle : >
• qoute: "

markdown:

• qoute: >

I love the product for everything, but the fact that you are willing to change markdown syntax makes me feel like you want to invent too much and therefore I am not able to be as portable to anything else. I just want to be a ravid fan because I want, not because I am "stuck" with how I write the markdown.

Doc for Slack codeblock markdown is wrong

Codeblock is supported staring and ending with 3 backticks, the ticks can be on it's own line or on the same line as the start/end of the text

```this
is a
codeblock```

```
this
is a
codeblock
```

How to add rel=“nofollow” or rel=“follow” in markdown file?

I want to add rel in my a href link.

HTML Formatting

Hi,

May HTML examples be formatted like this for increased readability?

<ul>  
   <li>First item</li>  
   <li>Second item</li>  
   <li>Third item</li>  
   <li>Fourth item</li>  
</ul>  

Some Markdown Code isn't correctly displayed on website

For example: https://www.markdownguide.org/extended-syntax/#strikethrough

Maybe it's a problem by HTML formatting?

Links to libraries that support this documented flavor of markdown?

I tried some of the features mentioned in your docs and they didn't work on the library I was using. It would nice to know which libraries I can use that support the flavor of markdown documented here.

Issue with VS Code docs

task list added to vscode

Issue with Dillinger docs

I was able to access dillinger.io yesterday for a class project however today I am unable to. It says that my computer can connect to it, however the host is not responding.

Update to tools

HI

I propose 2 tools .

pleroma
discourse

Pierre

Issue with GitBook docs: markdown footnotes

Please consider providing support for markdown footnotes syntax.

Add HedgeDoc to tool list

I'm one of the devs that work on HedgeDoc. Please add our project to the tool list. It's a community driven hard fork of the Codimd that you already have in your list and was once also called CodiMD. If you want to know more about our name confusion then feel free to read about it on our history page.

Issue with Boostnote docs

It is indicated that boostnote does not support some markdown features. I believe the items listed as unsupported are incorrect.

I tested the following in boostnote and they all appear to be working as expected in BoostNote version 0.15.3:

• Footnotes
• Definition Lists
• Emoji (shortcodes)
• HTML

I agree with your assessment of the "Heading IDs" feature. It does not appear to be supported.

thanks!

Recommend against using emphasis in middle of a word

As you say, "Markdown applications don’t agree on how to handle underscores in the middle of a word" and "Markdown applications don’t agree on how to handle underscores in the middle of a word". But instead of recommending to use asterisks, I recommend that you recommend to not use this feature at all.

I think this capability is the most useless features of the original Markdown. I can't think of any use cases at all. And I can think of many times when having a coding keyword such as my_code_variable is rendered wrong because I didn't put the word inside of backticks. This hasn't happened to me much but I imagine regular expressions that aren't enclosed in backticks would also be a problem. This is an abomination and all Markdown renderers should simply drop this design bug.

Team viewer

Feature Request: Table showing the Markdown Support by editor

Pitch

Hi all. I'm proposing a feature similar to the markdown support that is shown in the tools page for each editor.

This would be a page that would combine the support pages of each editor into a single table for the purpose of cross referencing. This would allow new users to be able to easily compare editors on a single page.

The support Green, yellow and red colours would still be present. But the notes would be missing on this page.

The notes for the partial sections will redirect to the that tool's markdown support page.

Acceptance Criteria:

• Each Markdown support element is shown on the combined table's y axis
• Each tool/editor is present on the x axis of the table
• The support for each tool on specified elements are present
• Each specified markdown element matches the markdown support page for that editor/tool (being either Yes, Partial, No)
• All Partially supported elements shown links to the original editors support page so that the user may see the full explanation (notes).

Alignment of nested blockquote

https://www.markdownguide.org/basic-syntax/#nested-blockquotes currently has

> Dorothy followed her through many of the beautiful rooms in her castle.
>
>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

Shouldn't that be

> > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

with a space between the >s?
I would think that you would want to align Dorothy with > The Witch.

To drive home the point, imagine if the nesting is 5 levels deep and (1) you're trying to figure out alignment or (2) you're trying to use column-oriented editor commands (such as vim's visual block) to manipulate indentation levels: the inconsistent alignment would make things a lot harder.

This is becoming much more important as Obsidian, MS Markdown, and Github are starting to support blockquote-based callouts and nesting happens very often now.

update to https://www.markdownguide.org/getting-started#additional-resources

Hello. I'm new to the Markdown world, so thanks for putting this resource together. I've been clicking around and on page https://www.markdownguide.org/getting-started#additional-resources you list Codecademy’s Mastering Markdown course: A free and interactive lesson that allows you to experiment with Markdown.

The intended page is: https://www.codecademy.com/courses/web-intermediate-en-Bw3bg/0/1
but the resulting page, https://www.codecademy.com/catalog/subject/all?composer_redirect=course, says: "As of July 5, 2018, this course is no longer supported. Check out our catalog for the latest course offerings."

It would appear that https://www.markdowntutorial.com/ is the way to go.

Cheers and thanks again,

Ron

PDF Sheet

I find this resource the ultimate markdown cheatsheet. Can we have it as PDF, please? Good work

[](https://miro.medium.com/max/700/1*VcHVCyRSAOF3V6Ldi0iXOQ.jpeg Thanks)

Issue with Notion docs

How do I post a link in Notion? You say here to use /link instead of Markdown, but /link doesn't look like it is there anymore.

I just want this:

to not link to an internal page, but an external page somewhere else on the internet. Thanks!

markdown-cheat-sheet.md asset file Image link example references file that doesn't exist

The assets/markdown-cheat-sheet.md asset file Image link example references file that doesn't exist. I checked the images/ directory in case it was there but did not find it.

### Image

![alt text](image.jpg)

Issue with iA Writer docs

iA Writer supports highlight.

Issue with Obsidian docs

Hello! I was searching for Obsidian super/sub-scrip capabilities when I found the documentation on the site. When checking the super/subsection, I found that the HTML-tagged super and sub-script syntax works! I'm not sure if that would mean that it is "partial" compatibility for not being compatible with the up carat syntax, but should probably at least list partial compatibility.

Attached screenshots showing this working!

Blockquote style is broken

• While explaining the use of block-quote syntax, the rendered text isn't formatted differently.
• this might make it confusing for someone unfamiliar with HTML, or coming from a non-web background.

Revise Why Use Markdown section to mention ability to diff

Received via email:

One additional point to the topic 'Why Use Markdown?' with the context 'why people use Markdown instead of a WYSIWYG editor'. An additional reason is that is comparable with a diff tool (based on text). Maybe you want add this as well, imho it is important too.

GitHub Flavored Markdown (GFM) page?

Thoughts on adding a "Tools" entry for GitHub Flavored Markdown (GFM)?

It's already mentioned in several places:
https://github.com/mattcone/markdown-guide/search?q=github+flavored

... But seems worthy of its own page to me!

Also, very very minor nitpick, but there is some slight inconsistency with how GFM is mentioned at the moment:

"(GFM)" suffix, external link:

• _extended-syntax/availability.md
• _tools/typora.md

"(GFM)" suffix, no external link:

• _tools/simpleen.md

No "(GFM)" suffix, no external link:

• _tools/madoko.md
• _tools/zettlr.md

Issue with Dawin (محرر دوّن) docs

the word "Dawin" does not mean "writer", it means the verb "Document"

Issue with Mark Text docs

Mark Text's official website has lost its domain according to the information I found by whois,

Domain Name: marktext.app
Registry Domain ID: 34FB4F0B5-APP
Registrar WHOIS Server: whois.godaddy.com
Registrar URL: https://www.godaddy.com/
Updated Date: 2022-05-15T08:21:20Z
Creation Date: 2019-04-03T15:21:52Z
Registry Expiry Date: 2022-04-03T15:21:52Z
Registrar: GoDaddy.com, LLC
Registrar IANA ID: 146
Registrar Abuse Contact Email: [email protected]
Registrar Abuse Contact Phone: [phone]
Domain Status: pendingDelete https://icann.org/epp#pendingDelete
Domain Status: redemptionPeriod https://icann.org/epp#redemptionPeriod
Registry Registrant ID: REDACTED FOR PRIVACY
Registrant Name: REDACTED FOR PRIVACY
Registrant Street: REDACTED FOR PRIVACY
Registrant Street:
Registrant City: REDACTED FOR PRIVACY
Registrant State/Province: Shanghai
Registrant Postal Code: REDACTED FOR PRIVACY
Registrant Country: CN
Registrant Phone: REDACTED FOR PRIVACY
Registrant Email: Please query the WHOIS server of the owning registrar identified in this output for information on how to contact the Registrant, Admin, or Tech contact of the queried domain name.
Registry Admin ID: REDACTED FOR PRIVACY
Admin Name: REDACTED FOR PRIVACY
Admin Street: REDACTED FOR PRIVACY
Admin Street:
Admin City: REDACTED FOR PRIVACY
Admin State/Province: REDACTED FOR PRIVACY
Admin Postal Code: REDACTED FOR PRIVACY
Admin Country: REDACTED FOR PRIVACY
Admin Phone: REDACTED FOR PRIVACY
Admin Email: Please query the WHOIS server of the owning registrar identified in this output for information on how to contact the Registrant, Admin, or Tech contact of the queried domain name.
Registry Tech ID: REDACTED FOR PRIVACY
Tech Name: REDACTED FOR PRIVACY
Tech Street: REDACTED FOR PRIVACY
Tech Street:
Tech City: REDACTED FOR PRIVACY
Tech State/Province: REDACTED FOR PRIVACY
Tech Postal Code: REDACTED FOR PRIVACY
Tech Country: REDACTED FOR PRIVACY
Tech Phone: REDACTED FOR PRIVACY
Tech Email: Please query the WHOIS server of the owning registrar identified in this output for information on how to contact the Registrant, Admin, or Tech contact of the queried domain name.
Registry Billing ID: REDACTED FOR PRIVACY
Billing Name: REDACTED FOR PRIVACY
Billing Street: REDACTED FOR PRIVACY
Billing Street:
Billing City: REDACTED FOR PRIVACY
Billing State/Province: REDACTED FOR PRIVACY
Billing Postal Code: REDACTED FOR PRIVACY
Billing Country: REDACTED FOR PRIVACY
Billing Phone: REDACTED FOR PRIVACY
Billing Email: Please query the WHOIS server of the owning registrar identified in this output for information on how to contact the Registrant, Admin, or Tech contact of the queried domain name.
Name Server: ns45.domaincontrol.com
Name Server: ns46.domaincontrol.com
DNSSEC: unsigned
URL of the ICANN Whois Inaccuracy Complaint Form: https://www.icann.org/wicf/
>>> Last update of WHOIS database: 2022-06-04T03:09:51Z <<<

For more information on Whois status codes, please visit https://icann.org/epp

Please query the WHOIS server of the owning registrar identified in this
output for information on how to contact the Registrant, Admin, or Tech
contact of the queried domain name.

WHOIS information is provided by Charleston Road Registry Inc. (CRR) solely
for query-based, informational purposes. By querying our WHOIS database, you
are agreeing to comply with these terms
(https://www.registry.google/about/whois-disclaimer.html) and acknowledge
that your information will be used in accordance with CRR's Privacy Policy
(https://www.registry.google/about/privacy.html), so please read those
documents carefully.  Any information provided is "as is" without any
guarantee of accuracy. You may not use such information to (a) allow,
enable, or otherwise support the transmission of mass unsolicited,
commercial advertising or solicitations; (b) enable high volume, automated,
electronic processes that access the systems of CRR or any ICANN-Accredited
Registrar, except as reasonably necessary to register domain names or modify
existing registrations; or (c) engage in or support unlawful behavior. CRR
reserves the right to restrict or deny your access to the Whois database,
and may modify these terms at any time.

which is why now the website is not accessible.

Reference-style Links

The example of Reference-style Links is weird. Should the second part be

[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'

[1] is the index of [hobbit-hole][1] rather than [hobbit-hole]

Issue with Modako docs: Title is misspelled

"Modako" is a misspelling of "Madoko".

• https://www.markdownguide.org/tools/modako/
• https://www.markdownguide.org/tools/

Can I help with the translation into Spanish?

This project is awesome; I want to share this with those who didn't speak English as a first language.

The guidelines for contributing is enough for making a PR for the Spanish version?

Interactive pageNav

Hi, I liked the interactive pageNav you had on your site. Wished to know how did you do that?