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.
Link
Inline Link
Inline links is created by wrapping link text in brackets [], followed by URL in parentheses () for e.g. [link text](URL)
Inline Link with Title
Inline Link can also be created with optional title which is displayed when hover on the link.
Inline Link with URL and Email Address
URL or email address can quickly be turned into a clickable link by wrapping it in angle brackets <>
Automatic URL and Email Address Link
💡 Many markdown processors (but not all) automatically turns URL and Email Address into clickable link even without wrapping in <>
Reference Links
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. 
Inline Image with Title
Image can also be created with optional title which is displayed when hover on the image for e.g. 
Inline Image with Link
Clickable image can also be created with link URL for e.g. [](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