The Markdown Syntax Guide – Coding N Concepts



The Markdown Syntax Guide – Coding N Concepts | ninjasquad

In this comprehensive guide, we’ll learn Markdown syntax with examples.

Overview

Markdown is a lightweight markup language that is used to format and style the content of text document. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.

You write markdown in plain text format, which is easier to read and write for most humans, and then Markdown processor convert the plain text into HTML.

There are many markdown processors available. Markdown syntax and support for elements may slightly differ depending upon which markdown processor is being used.

Let’s learn how to format text using various Markdown syntax with examples:-

Block Elements

Headings

Hash # is used to create headings. The number of hashes denotes the heading level for e.g. ### denotes the third level heading.

✅ Always add space between # and the heading for e.g. # Heading 1 works but #Heading 1 doesn’t.
✅ Headings are supported by all Markdown processors.

Alternate syntax for h1 and h2

Alternate syntax is available for first and second level of headings. Add any number of equal signs = and hyphens - below the text for first level and second level heading respectively.

Paragraphs

Single Paragraph

A simple line of text in Markdown creates a paragraph.

Multiple Paragraphs

A blank line is used to separate paragraphs.

If a blank line is not used then it is considered as a single paragraph even if the text is in multiple lines.

Paragraph with line break

To add a line break in a paragraph, end a line with two or more spaces.

Note: ” › ” denotes the space in above example.

❌ Do not indent the paragraph with spaces or tabs. It may render different output by different Markdown processors.
✅ Always keep paragraph left-aligned.
✅ Paragraphs are supported by all Markdown processors.

List

Ordered List

Ordered or Numbered list can be rendered by adding a number followed by period . for e.g. 1. before text.

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

Nested Ordered List

Nested list items can be created by adding indentation to the line. Each indentation creates a deeper nested level.

❌ You can also use parenthesis 1) instead of period 1. but not recommended, because few markdown processor support this.
✅ Ordered lists are supported by all Markdown processors.

Unordered List

Unordered list can be rendered by adding hyphen (or dash) -, asterisk *, or plus + in front of a text.

Nested Unordered List

Nested list items can be created by adding indentation to the line. Each indentation creates deeper nested level.

❌ Do not mix and match hyphen (or dash) -, asterisk *, or plus + in the same list. Different markdown processors handle it in differently so pick one and stick with it.
✅ Unordered lists are supported by all Markdown processors.

Escape period in ordered and unordered list

If you start an ordered or unordered list item with a number followed by a period for e.g. 1. 1. or - 1. then it is treated as nested ordered list.

You can get rid of this by adding a backslash \ in front of period for e.g. - 1\.

Escape dash, asterisk and plus in ordered and unordered list

If you start an ordered or unordered list item with dash -, asterisk * or plus + sign then it is treated as nested unordered list. You can escape this by adding a backslash \ in front of them for e.g. \-, \* or \+

Definition Lists

Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon : followed by a space and the definition.

❌ Definition lists are NOT supported by all Markdown processors.

Blockquotes

Blockquotes with single paragraph

Blockquotes is created by adding greater sign > in front of a text.

Blockquotes with multiple paragraphs

Blockquotes can contain multiple paragraphs. Add a greater sign > on the blank lines as well between the paragraphs.

Nested Blockquotes

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional > for each nested level.

Formatted Blockquotes

Blockquotes can be formatted with other elements such as headers, lists, emphasis and code blocks. Not all the elements works though, try them and see yourself.

✅ Blockquotes are supported by all Markdown processors.

Code Blocks

Code blocks are used to write programming code snippet. You can create a code block by indenting every line of the block by at least 4 spaces or 1 tab

Note: ” › ” denotes the space in above example.

Fenced Code Blocks

If you find adding 4 spaces or one tab on each line of the block is more inconvenient then some markdown processors also support three backticks ``` or three tildes ~~~ before and after the code block.

Syntax Highlighting

Many Markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language next to the three backticks for e.g. ```javascript

Note that syntax highlighting support for a language and how the syntax are displayed for that language varies across different Markdown processors. You can try from this full list of languages, if that works for you:-

abap ('*.abap')
ada ('*.adb', '*.ads', '*.ada')
ahk ('*.ahk', '*.ahkl')
apacheconf ('.htaccess', 'apache.conf', 'apache2.conf')
applescript ('*.applescript')
as ('*.as')
as3 ('*.as')
asy ('*.asy')
bash ('*.sh', '*.ksh', '*.bash', '*.ebuild', '*.eclass')
bat ('*.bat', '*.cmd')
befunge ('*.befunge')
blitzmax ('*.bmx')
boo ('*.boo')
brainfuck ('*.bf', '*.b')
c ('*.c', '*.h')
cfm ('*.cfm', '*.cfml', '*.cfc')
cheetah ('*.tmpl', '*.spt')
cl ('*.cl', '*.lisp', '*.el')
clojure ('*.clj', '*.cljs')
cmake ('*.cmake', 'CMakeLists.txt')
coffeescript ('*.coffee')
console ('*.sh-session')
control ('control')
cpp ('*.cpp', '*.hpp', '*.c++', '*.h++', '*.cc', '*.hh', '*.cxx', '*.hxx', '*.pde')
csharp ('*.cs')
css ('*.css')
cython ('*.pyx', '*.pxd', '*.pxi')
d ('*.d', '*.di')
delphi ('*.pas')
diff ('*.diff', '*.patch')
dpatch ('*.dpatch', '*.darcspatch')
duel ('*.duel', '*.jbst')
dylan ('*.dylan', '*.dyl')
erb ('*.erb')
erl ('*.erl-sh')
erlang ('*.erl', '*.hrl')
evoque ('*.evoque')
factor ('*.factor')
felix ('*.flx', '*.flxh')
fortran ('*.f', '*.f90')
gas ('*.s', '*.S')
genshi ('*.kid')
glsl ('*.vert', '*.frag', '*.geo')
gnuplot ('*.plot', '*.plt')
go ('*.go')
groff ('*.(1234567)', '*.man')
haml ('*.haml')
haskell ('*.hs')
html ('*.html', '*.htm', '*.xhtml', '*.xslt')
hx ('*.hx')
hybris ('*.hy', '*.hyb')
ini ('*.ini', '*.cfg')
io ('*.io')
ioke ('*.ik')
irc ('*.weechatlog')
jade ('*.jade')
java ('*.java')
js ('*.js')
jsp ('*.jsp')
lhs ('*.lhs')
llvm ('*.ll')
logtalk ('*.lgt')
lua ('*.lua', '*.wlua')
make ('*.mak', 'Makefile', 'makefile', 'Makefile.*', 'GNUmakefile')
mako ('*.mao')
maql ('*.maql')
mason ('*.mhtml', '*.mc', '*.mi', 'autohandler', 'dhandler')
markdown ('*.md')
modelica ('*.mo')
modula2 ('*.def', '*.mod')
moocode ('*.moo')
mupad ('*.mu')
mxml ('*.mxml')
myghty ('*.myt', 'autodelegate')
nasm ('*.asm', '*.ASM')
newspeak ('*.ns2')
objdump ('*.objdump')
objectivec ('*.m')
objectivej ('*.j')
ocaml ('*.ml', '*.mli', '*.mll', '*.mly')
ooc ('*.ooc')
perl ('*.pl', '*.pm')
php ('*.php', '*.php(345)')
postscript ('*.ps', '*.eps')
pot ('*.pot', '*.po')
pov ('*.pov', '*.inc')
prolog ('*.prolog', '*.pro', '*.pl')
properties ('*.properties')
protobuf ('*.proto')
py3tb ('*.py3tb')
pytb ('*.pytb')
python ('*.py', '*.pyw', '*.sc', 'SConstruct', 'SConscript', '*.tac')
rb ('*.rb', '*.rbw', 'Rakefile', '*.rake', '*.gemspec', '*.rbx', '*.duby')
rconsole ('*.Rout')
rebol ('*.r', '*.r3')
redcode ('*.cw')
rhtml ('*.rhtml')
rst ('*.rst', '*.rest')
sass ('*.sass')
scala ('*.scala')
scaml ('*.scaml')
scheme ('*.scm')
scss ('*.scss')
smalltalk ('*.st')
smarty ('*.tpl')
sourceslist ('sources.list')
splus ('*.S', '*.R')
sql ('*.sql')
sqlite3 ('*.sqlite3-console')
squidconf ('squid.conf')
ssp ('*.ssp')
tcl ('*.tcl')
tcsh ('*.tcsh', '*.csh')
tex ('*.tex', '*.aux', '*.toc')
text ('*.txt')
v ('*.v', '*.sv')
vala ('*.vala', '*.vapi')
vbnet ('*.vb', '*.bas')
velocity ('*.vm', '*.fhtml')
vim ('*.vim', '.vimrc')
xml ('*.xml', '*.xsl', '*.rss', '*.xslt', '*.xsd', '*.wsdl')
xquery ('*.xqy', '*.xquery')
xslt ('*.xsl', '*.xslt')
yaml ('*.yaml', '*.yml')

✅ Code block (without Syntax highlighting) is supported by all Markdown processors.
❌ Code blocks with Syntax highlighting is NOT supported by all Markdown processors.

Horizontal Rules

You can use three or more asterisks ***, dashes ---, or underscores ___ to create a horizontal rule. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines:-

* * *

***

*****

- - -

---------------------------------------

produce a horizontal rule like below:-






✅ Horizontal rules are supported by all Markdown processors.

Tables

To create a table, use three or more hyphens --- to create each column’s header, and use pipes | to separate each column.

You can optionally add pipes on either end of the table.

Number of hyphens --- doesn’t affect the width of the column. For e.g. both columns will have equal (or auto) width in rendered table even though numbers of - are less in first column.

Table Column Text Alignment

You can align text in the columns to the left, right, or center by adding a colon : to the left, right, or on both side of the hyphens within the header row.

Text Align Syntax
left :---
center :---:
right ---:

Table Cell Text Formatting

You can format the text within table cells. For example, you can add links, code (not code blocks), and emphasis. You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags.

Escape Pipe in Tables

If you want to use | character as a text in the table then you can escape it with blackslash i.e. \|

❌ Tables are NOT supported by all Markdown processors.

Task Lists

Task lists allow you to create a list of items with checkboxes. In Markdown applications that support task lists, checkboxes will be displayed next to the content.

To create a task list,
add - [] to create unchecked task list item, and
add - [x] to create checked task list item

❌ Task lists are NOT supported by all Markdown processors.

Span Elements

Emphasis

Bold

Add two asterisks ** or two underscores __ before and after a word for e.g. **bold** or __bold__ to render as bold.

You can only use asterisks ** and not underscores __ to make part of the word bold. Using __ in part of the word considered as underscore _ and not syntax.

❌ Do not to mix both asterisk and underscore for e.g. *_bold_*, _*bold*_, or _*bold_*. It may render different output by different Markdown processors.
✅ Bold is supported by all Markdown processors.

Italic

Add an asterisk * or underscore _ before and after a word for e.g. *italic* or _italic_ to render as italic.

You can only use asterisk * and not underscores _ to make part of the word italic. Using _ in part of the word considered as underscore _ and not syntax.

✅ Italic is supported by all Markdown processors.

Strikethrough

Add two tilde ~~ before and after a word for e.g. ~~strike~~ to render as strike.

❌ Strikethrough is NOT supported by all Markdown processors.

Bold, Italic and Strike

You can join asterisk *, underscore _ and tilde ~ together for e.g. **_~~bold, italic, and strike~~_** to render bold, italic and strike at the same time.

Escape asterisk, underscore and tilde in emphasis

You can escape the asterisk *, underscore _ and tilde ~ characters to use them in literal way by adding a backslash \ in front of that character.

Inline links is created by wrapping link text in brackets [], followed by URL in parentheses () for e.g. [link text](URL)

Inline Link can also be created with optional title which is displayed when hover on the link.

URL or email address can quickly be turned into a clickable link by wrapping it in angle brackets <>

💡 Many markdown processors (but not all) automatically turns URL and Email Address into clickable link even without wrapping in <>

Reference-style links are constructed in two parts: first part is link text which you keep inline and the second part is URL which you define somewhere else in the document.

❌ Do not use space in the middle of the URL for e.g. https://codingnconcepts.com/markdown/markdown-syntax/(https://www.example.com/my great page), use encoded URL https://codingnconcepts.com/markdown/markdown-syntax/(https://www.example.com/my%20great%20page) instead.
✅ Links and email addresses are supported by all Markdown processors.

Image

Inline Image

Image is created by starting with exclamation !, followed by alt text in brackets [], followed by image path or URL in parentheses () for e.g. ![alt-text](image-path)

Inline Image with Title

Image can also be created with optional title which is displayed when hover on the image for e.g. ![alt-text](image-path "Title")

Clickable image can also be created with link URL for e.g. [![alt-text](image-path "Title")](URL)

Reference Image

Reference-style images are constructed in two parts: first part is alt text which you keep inline and the second part is image patg which you define somewhere else in the document.

✅ Images are supported by all Markdown processors.

Code

Enclose the text in backticks ` to display that as a code for e.g `code`.

Escape backticks in code

You can escape the backtick ` character to use it in literal way by enclosing the code text in double backticks ``.

Note the space between double backticks `` and `nano`, otherwise it won’t work.

Escaping Characters

Sometime we want to display the characters in literal way which are used as a Markdown syntax. In such cases, add a backslash \ in front of the character.

You can escape the following characters in Markdown:-

Summary

Congratulations! We have learned all the syntax supported by most of the Markdown processors.

You can further read following useful resources:-



Source: Internet

Leave a Comment

We are offering free coding tuts

X