9/4/13

Daring Fireball: Markdown Syntax Documentation

ByJohnGruber

Markdown: Syntax
Main Basics Syntax License Dingus Overview Philosophy InlineHTML AutomaticEscapingforSpecialCharacters BlockElements ParagraphsandLineBreaks Headers Blockquotes Lists CodeBlocks HorizontalRules SpanElements Links Emphasis Code Images Miscellaneous BackslashEscapes AutomaticLinks Note:ThisdocumentisitselfwrittenusingMarkdownyoucanseethesourceforitby adding.texttotheURL.

OVERVIEW

PHIL OSOPHY
Markdownisintendedtobeaseasytoreadandeasytowriteasisfeasible. Readability,however,isemphasizedaboveallelse.AMarkdownformatteddocument shouldbepublishableasis,asplaintext,withoutlookinglikeitsbeenmarkedupwith

daringfireball.net/projects/markdown/syntax#header

1/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

tagsorformattinginstructions.WhileMarkdownssyntaxhasbeeninfluencedbyseveral existingtexttoHTMLfiltersincludingSetext,atx,Textile,reStructuredText,Grutatext, andEtTextthesinglebiggestsourceofinspirationforMarkdownssyntaxistheformat ofplaintextemail. Tothisend,Markdownssyntaxiscomprisedentirelyofpunctuationcharacters,which punctuationcharactershavebeencarefullychosensoastolooklikewhattheymean. E.g.,asterisksaroundawordactuallylooklike*emphasis*.Markdownlistslooklike, well,lists.Evenblockquoteslooklikequotedpassagesoftext,assumingyouveever usedemail.

INL INEHT M L
Markdownssyntaxisintendedforonepurpose:tobeusedasaformatforwritingforthe web. MarkdownisnotareplacementforHTML,orevenclosetoit.Itssyntaxisverysmall, correspondingonlytoaverysmallsubsetofHTMLtags.Theideaisnottocreatea syntaxthatmakesiteasiertoinsertHTMLtags.Inmyopinion,HTMLtagsarealready easytoinsert.TheideaforMarkdownistomakeiteasytoread,write,andeditprose. HTMLisapublishingformatMarkdownisawritingformat.Thus,Markdownsformatting syntaxonlyaddressesissuesthatcanbeconveyedinplaintext. ForanymarkupthatisnotcoveredbyMarkdownssyntax,yousimplyuseHTMLitself. TheresnoneedtoprefaceitordelimitittoindicatethatyoureswitchingfromMarkdown toHTMLyoujustusethetags. TheonlyrestrictionsarethatblocklevelHTMLelementse.g.< d i v > ,< t a b l e > ,< p r e > ,
< p > ,etc.mustbeseparatedfromsurroundingcontentbyblanklines,andthestartand

endtagsoftheblockshouldnotbeindentedwithtabsorspaces.Markdownissmart enoughnottoaddextra(unwanted)< p > tagsaroundHTMLblockleveltags. Forexample,toaddanHTMLtabletoaMarkdownarticle: T h i s i s a r e g u l a r p a r a g r a p h . < t a b l e > < t r > < t d > F o o < / t d > < / t r > < / t a b l e > T h i s i s a n o t h e r r e g u l a r p a r a g r a p h . NotethatMarkdownformattingsyntaxisnotprocessedwithinblocklevelHTMLtags. E.g.,youcantuseMarkdownstyle* e m p h a s i s * insideanHTMLblock.

daringfireball.net/projects/markdown/syntax#header

2/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

SpanlevelHTMLtagse.g.< s p a n > ,< c i t e > ,or< d e l > canbeusedanywhereina Markdownparagraph,listitem,orheader.Ifyouwant,youcanevenuseHTMLtags insteadofMarkdownformattinge.g.ifyoudprefertouseHTML< a > or< i m g > tags insteadofMarkdownslinkorimagesyntax,gorightahead. UnlikeblocklevelHTMLtags,Markdownsyntaxisprocessedwithinspanleveltags.

AUT OM AT ICESCAPINGF ORSPECIAL CHARACT ERS

InHTML,therearetwocharactersthatdemandspecialtreatment:< and& .Leftangle bracketsareusedtostarttagsampersandsareusedtodenoteHTMLentities.Ifyou wanttousethemasliteralcharacters,youmustescapethemasentities,e.g.& l t ,and
& a m p .

Ampersandsinparticulararebedevilingforwebwriters.Ifyouwanttowriteabout AT&T,youneedtowriteA T & a m p T .Youevenneedtoescapeampersandswithin URLs.Thus,ifyouwanttolinkto: h t t p : / / i m a g e s . g o o g l e . c o m / i m a g e s ? n u m = 3 0 & q = l a r r y + b i r d youneedtoencodetheURLas: h t t p : / / i m a g e s . g o o g l e . c o m / i m a g e s ? n u m = 3 0 & a m p q = l a r r y + b i r d inyouranchortagh r e f attribute.Needlesstosay,thisiseasytoforget,andisprobably thesinglemostcommonsourceofHTMLvalidationerrorsinotherwisewellmarkedup websites. Markdownallowsyoutousethesecharactersnaturally,takingcareofallthenecessary escapingforyou.IfyouuseanampersandaspartofanHTMLentity,itremains unchangedotherwiseitwillbetranslatedinto& a m p . So,ifyouwanttoincludeacopyrightsymbolinyourarticle,youcanwrite: & c o p y andMarkdownwillleaveitalone.Butifyouwrite: A T & T Markdownwilltranslateitto: A T & a m p T Similarly,becauseMarkdownsupportsinlineHTML,ifyouuseanglebracketsas delimitersforHTMLtags,Markdownwilltreatthemassuch.Butifyouwrite:

daringfireball.net/projects/markdown/syntax#header

3/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

4 < 5 Markdownwilltranslateitto: 4 & l t 5 However,insideMarkdowncodespansandblocks,anglebracketsandampersandsare alwaysencodedautomatically.ThismakesiteasytouseMarkdowntowriteaboutHTML code.(AsopposedtorawHTML,whichisaterribleformatforwritingaboutHTMLsyntax, becauseeverysingle< and& inyourexamplecodeneedstobeescaped.)

BLOCK ELEMENT S

PARAGRAPHSANDL INEBREAKS
Aparagraphissimplyoneormoreconsecutivelinesoftext,separatedbyoneormore blanklines.(Ablanklineisanylinethatlookslikeablanklinealinecontaining nothingbutspacesortabsisconsideredblank.)Normalparagraphsshouldnotbe indentedwithspacesortabs. TheimplicationoftheoneormoreconsecutivelinesoftextruleisthatMarkdown supportshardwrappedtextparagraphs.Thisdifferssignificantlyfrommostothertext toHTMLformatters(includingMovableTypesConvertLineBreaksoption)which translateeverylinebreakcharacterinaparagraphintoa< b r / > tag. Whenyoudowanttoinserta< b r / > breaktagusingMarkdown,youendalinewithtwo ormorespaces,thentypereturn. Yes,thistakesatadmoreefforttocreatea< b r / > ,butasimplisticeverylinebreakisa
< b r / > rulewouldntworkforMarkdown.Markdownsemailstyleblockquotingand

multiparagraphlistitemsworkbestandlookbetterwhenyouformatthemwith hardbreaks.

HEADERS
Markdownsupportstwostylesofheaders,Setextandatx. Setextstyleheadersareunderlinedusingequalsigns(forfirstlevelheaders)and dashes(forsecondlevelheaders).Forexample: T h i s i s a n H 1 = = = = = = = = = = = = =

daringfireball.net/projects/markdown/syntax#header

4/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

T h i s i s a n H 2 Anynumberofunderlining= sor swillwork. Atxstyleheadersuse16hashcharactersatthestartoftheline,correspondingto headerlevels16.Forexample: # T h i s i s a n H 1 # # T h i s i s a n H 2 # # # # # # T h i s i s a n H 6 Optionally,youmaycloseatxstyleheaders.Thisispurelycosmeticyoucanusethis ifyouthinkitlooksbetter.Theclosinghashesdontevenneedtomatchthenumberof hashesusedtoopentheheader.(Thenumberofopeninghashesdeterminesthe headerlevel.): # T h i s i s a n H 1 # # # T h i s i s a n H 2 # # # # # T h i s i s a n H 3 # # # # # #

BL OCKQUOT ES
Markdownusesemailstyle> charactersforblockquoting.Ifyourefamiliarwithquoting passagesoftextinanemailmessage,thenyouknowhowtocreateablockquotein Markdown.Itlooksbestifyouhardwrapthetextandputa> beforeeveryline: > T h i s i s a b l o c k q u o t e w i t h t w o p a r a g r a p h s . L o r e m i p s u m d o l o r s i t a m e t , > c o n s e c t e t u e r a d i p i s c i n g e l i t . A l i q u a m h e n d r e r i t m i p o s u e r e l e c t u s . > V e s t i b u l u m e n i m w i s i , v i v e r r a n e c , f r i n g i l l a i n , l a o r e e t v i t a e , r i s u s . > > D o n e c s i t a m e t n i s l . A l i q u a m s e m p e r i p s u m s i t a m e t v e l i t . S u s p e n d i s s e > i d s e m c o n s e c t e t u e r l i b e r o l u c t u s a d i p i s c i n g . Markdownallowsyoutobelazyandonlyputthe> beforethefirstlineofahardwrapped paragraph: > T h i s i s a b l o c k q u o t e w i t h t w o p a r a g r a p h s . L o r e m i p s u m d o l o r s i t a m e t , c o n s e c t e t u e r a d i p i s c i n g e l i t . A l i q u a m h e n d r e r i t m i p o s u e r e l e c t u s . V e s t i b u l u m e n i m w i s i , v i v e r r a n e c , f r i n g i l l a i n , l a o r e e t v i t a e , r i s u s . > D o n e c s i t a m e t n i s l . A l i q u a m s e m p e r i p s u m s i t a m e t v e l i t . S u s p e n d i s s e

daringfireball.net/projects/markdown/syntax#header

5/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

i d s e m c o n s e c t e t u e r l i b e r o l u c t u s a d i p i s c i n g . Blockquotescanbenested(i.e.ablockquoteinablockquote)byaddingadditional levelsof> : > T h i s i s t h e f i r s t l e v e l o f q u o t i n g . > > > T h i s i s n e s t e d b l o c k q u o t e . > > B a c k t o t h e f i r s t l e v e l . BlockquotescancontainotherMarkdownelements,includingheaders,lists,andcode blocks: > # # T h i s i s a h e a d e r . > > 1 . T h i s i s t h e f i r s t l i s t i t e m . > 2 . T h i s i s t h e s e c o n d l i s t i t e m . > > H e r e ' s s o m e e x a m p l e c o d e : > > r e t u r n s h e l l _ e x e c ( " e c h o $ i n p u t | $ m a r k d o w n _ s c r i p t " ) Anydecenttexteditorshouldmakeemailstylequotingeasy.Forexample,withBBEdit, youcanmakeaselectionandchooseIncreaseQuoteLevelfromtheTextmenu.

L IST S
Markdownsupportsordered(numbered)andunordered(bulleted)lists. Unorderedlistsuseasterisks,pluses,andhyphensinterchangablyaslistmarkers: * R e d * G r e e n * B l u e isequivalentto: + R e d + G r e e n + B l u e and: R e d G r e e n B l u e

daringfireball.net/projects/markdown/syntax#header

6/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

Orderedlistsusenumbersfollowedbyperiods: 1 . B i r d 2 . M c H a l e 3 . P a r i s h Itsimportanttonotethattheactualnumbersyouusetomarkthelisthavenoeffecton theHTMLoutputMarkdownproduces.TheHTMLMarkdownproducesfromtheabove listis: < o l > < l i > B i r d < / l i > < l i > M c H a l e < / l i > < l i > P a r i s h < / l i > < / o l > IfyouinsteadwrotethelistinMarkdownlikethis: 1 . B i r d 1 . M c H a l e 1 . P a r i s h oreven: 3 . B i r d 1 . M c H a l e 8 . P a r i s h youdgettheexactsameHTMLoutput.Thepointis,ifyouwantto,youcanuseordinal numbersinyourorderedMarkdownlists,sothatthenumbersinyoursourcematchthe numbersinyourpublishedHTML.Butifyouwanttobelazy,youdonthaveto. Ifyoudouselazylistnumbering,however,youshouldstillstartthelistwiththenumber 1.Atsomepointinthefuture,Markdownmaysupportstartingorderedlistsatanarbitrary number. Listmarkerstypicallystartattheleftmargin,butmaybeindentedbyuptothreespaces. Listmarkersmustbefollowedbyoneormorespacesoratab. Tomakelistslooknice,youcanwrapitemswithhangingindents: * L o r e m i p s u m d o l o r s i t a m e t , c o n s e c t e t u e r a d i p i s c i n g e l i t . A l i q u a m h e n d r e r i t m i p o s u e r e l e c t u s . V e s t i b u l u m e n i m w i s i , v i v e r r a n e c , f r i n g i l l a i n , l a o r e e t v i t a e , r i s u s . * D o n e c s i t a m e t n i s l . A l i q u a m s e m p e r i p s u m s i t a m e t v e l i t . S u s p e n d i s s e i d s e m c o n s e c t e t u e r l i b e r o l u c t u s a d i p i s c i n g . Butifyouwanttobelazy,youdonthaveto: * L o r e m i p s u m d o l o r s i t a m e t , c o n s e c t e t u e r a d i p i s c i n g e l i t .

daringfireball.net/projects/markdown/syntax#header

7/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

A l i q u a m h e n d r e r i t m i p o s u e r e l e c t u s . V e s t i b u l u m e n i m w i s i , v i v e r r a n e c , f r i n g i l l a i n , l a o r e e t v i t a e , r i s u s . * D o n e c s i t a m e t n i s l . A l i q u a m s e m p e r i p s u m s i t a m e t v e l i t . S u s p e n d i s s e i d s e m c o n s e c t e t u e r l i b e r o l u c t u s a d i p i s c i n g . Iflistitemsareseparatedbyblanklines,Markdownwillwraptheitemsin< p > tagsinthe HTMLoutput.Forexample,thisinput: * B i r d * M a g i c willturninto: < u l > < l i > B i r d < / l i > < l i > M a g i c < / l i > < / u l > Butthis: * B i r d * M a g i c willturninto: < u l > < l i > < p > B i r d < / p > < / l i > < l i > < p > M a g i c < / p > < / l i > < / u l > Listitemsmayconsistofmultipleparagraphs.Eachsubsequentparagraphinalistitem mustbeindentedbyeither4spacesoronetab: 1 . T h i s i s a l i s t i t e m w i t h t w o p a r a g r a p h s . L o r e m i p s u m d o l o r s i t a m e t , c o n s e c t e t u e r a d i p i s c i n g e l i t . A l i q u a m h e n d r e r i t m i p o s u e r e l e c t u s . V e s t i b u l u m e n i m w i s i , v i v e r r a n e c , f r i n g i l l a i n , l a o r e e t v i t a e , r i s u s . D o n e c s i t a m e t n i s l . A l i q u a m s e m p e r i p s u m s i t a m e t v e l i t . 2 . S u s p e n d i s s e i d s e m c o n s e c t e t u e r l i b e r o l u c t u s a d i p i s c i n g . Itlooksniceifyouindenteverylineofthesubsequentparagraphs,buthereagain, Markdownwillallowyoutobelazy: * T h i s i s a l i s t i t e m w i t h t w o p a r a g r a p h s . T h i s i s t h e s e c o n d p a r a g r a p h i n t h e l i s t i t e m . Y o u ' r e o n l y r e q u i r e d t o i n d e n t t h e f i r s t l i n e . L o r e m i p s u m d o l o r

daringfireball.net/projects/markdown/syntax#header

8/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

s i t a m e t , c o n s e c t e t u e r a d i p i s c i n g e l i t . * A n o t h e r i t e m i n t h e s a m e l i s t . Toputablockquotewithinalistitem,theblockquotes> delimitersneedtobeindented: * A l i s t i t e m w i t h a b l o c k q u o t e : > T h i s i s a b l o c k q u o t e > i n s i d e a l i s t i t e m . Toputacodeblockwithinalistitem,thecodeblockneedstobeindentedtwice8 spacesortwotabs: * A l i s t i t e m w i t h a c o d e b l o c k : < c o d e g o e s h e r e > Itsworthnotingthatitspossibletotriggeranorderedlistbyaccident,bywriting somethinglikethis: 1 9 8 6 . W h a t a g r e a t s e a s o n . Inotherwords,anumberperiodspacesequenceatthebeginningofaline.Toavoid this,youcanbackslashescapetheperiod: 1 9 8 6 \ . W h a t a g r e a t s e a s o n .

CODEBL OCKS
Preformattedcodeblocksareusedforwritingaboutprogrammingormarkupsource code.Ratherthanformingnormalparagraphs,thelinesofacodeblockareinterpreted literally.Markdownwrapsacodeblockinboth< p r e > and< c o d e > tags. ToproduceacodeblockinMarkdown,simplyindenteverylineoftheblockbyatleast4 spacesor1tab.Forexample,giventhisinput: T h i s i s a n o r m a l p a r a g r a p h : T h i s i s a c o d e b l o c k . Markdownwillgenerate: < p > T h i s i s a n o r m a l p a r a g r a p h : < / p > < p r e > < c o d e > T h i s i s a c o d e b l o c k . < / c o d e > < / p r e >

daringfireball.net/projects/markdown/syntax#header

9/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

Onelevelofindentation4spacesor1tabisremovedfromeachlineofthecode block.Forexample,this: H e r e i s a n e x a m p l e o f A p p l e S c r i p t : t e l l a p p l i c a t i o n " F o o " b e e p e n d t e l l willturninto: < p > H e r e i s a n e x a m p l e o f A p p l e S c r i p t : < / p > < p r e > < c o d e > t e l l a p p l i c a t i o n " F o o " b e e p e n d t e l l < / c o d e > < / p r e > Acodeblockcontinuesuntilitreachesalinethatisnotindented(ortheendofthe article). Withinacodeblock,ampersands(& )andanglebrackets(< and> )areautomatically convertedintoHTMLentities.ThismakesitveryeasytoincludeexampleHTMLsource codeusingMarkdownjustpasteitandindentit,andMarkdownwillhandlethehassle ofencodingtheampersandsandanglebrackets.Forexample,this: < d i v c l a s s = " f o o t e r " > & c o p y 2 0 0 4 F o o C o r p o r a t i o n < / d i v > willturninto: < p r e > < c o d e > & l t d i v c l a s s = " f o o t e r " & g t & a m p c o p y 2 0 0 4 F o o C o r p o r a t i o n & l t / d i v & g t < / c o d e > < / p r e > RegularMarkdownsyntaxisnotprocessedwithincodeblocks.E.g.,asterisksarejust literalasteriskswithinacodeblock.ThismeansitsalsoeasytouseMarkdowntowrite aboutMarkdownsownsyntax.

HORIZ ONT AL RUL ES

Youcanproduceahorizontalruletag(< h r / > )byplacingthreeormorehyphens, asterisks,orunderscoresonalinebythemselves.Ifyouwish,youmayusespaces betweenthehyphensorasterisks.Eachofthefollowinglineswillproduceahorizontal rule:

daringfireball.net/projects/markdown/syntax#header

10/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

* * * * * * * * * * *

SP AN ELEMENT S

L INKS
Markdownsupportstwostyleoflinks:inlineandreference. Inbothstyles,thelinktextisdelimitedby[squarebrackets]. Tocreateaninlinelink,useasetofregularparenthesesimmediatelyafterthelinktexts closingsquarebracket.Insidetheparentheses,puttheURLwhereyouwantthelinkto point,alongwithanoptionaltitleforthelink,surroundedinquotes.Forexample: T h i s i s [ a n e x a m p l e ] ( h t t p : / / e x a m p l e . c o m / " T i t l e " ) i n l i n e l i n k . [ T h i s l i n k ] ( h t t p : / / e x a m p l e . n e t / ) h a s n o t i t l e a t t r i b u t e . Willproduce: < p > T h i s i s < a h r e f = " h t t p : / / e x a m p l e . c o m / " t i t l e = " T i t l e " > a n e x a m p l e < / a > i n l i n e l i n k . < / p > < p > < a h r e f = " h t t p : / / e x a m p l e . n e t / " > T h i s l i n k < / a > h a s n o t i t l e a t t r i b u t e . < / p > Ifyourereferringtoalocalresourceonthesameserver,youcanuserelativepaths: S e e m y [ A b o u t ] ( / a b o u t / ) p a g e f o r d e t a i l s . Referencestylelinksuseasecondsetofsquarebrackets,insidewhichyouplacea labelofyourchoosingtoidentifythelink: T h i s i s [ a n e x a m p l e ] [ i d ] r e f e r e n c e s t y l e l i n k . Youcanoptionallyuseaspacetoseparatethesetsofbrackets: T h i s i s [ a n e x a m p l e ] [ i d ] r e f e r e n c e s t y l e l i n k .

daringfireball.net/projects/markdown/syntax#header

11/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

Then,anywhereinthedocument,youdefineyourlinklabellikethis,onalinebyitself: [ i d ] : h t t p : / / e x a m p l e . c o m / " O p t i o n a l T i t l e H e r e " Thatis: Squarebracketscontainingthelinkidentifier(optionallyindentedfromtheleft marginusinguptothreespaces) followedbyacolon followedbyoneormorespaces(ortabs) followedbytheURLforthelink optionallyfollowedbyatitleattributeforthelink,enclosedindoubleorsingle quotes,orenclosedinparentheses. Thefollowingthreelinkdefinitionsareequivalent: [ f o o ] : h t t p : / / e x a m p l e . c o m / " O p t i o n a l T i t l e H e r e " [ f o o ] : h t t p : / / e x a m p l e . c o m / ' O p t i o n a l T i t l e H e r e ' [ f o o ] : h t t p : / / e x a m p l e . c o m / ( O p t i o n a l T i t l e H e r e ) Note:ThereisaknownbuginMarkdown.pl1.0.1whichpreventssinglequotesfrom beingusedtodelimitlinktitles. ThelinkURLmay,optionally,besurroundedbyanglebrackets: [ i d ] : < h t t p : / / e x a m p l e . c o m / > " O p t i o n a l T i t l e H e r e " Youcanputthetitleattributeonthenextlineanduseextraspacesortabsforpadding, whichtendstolookbetterwithlongerURLs: [ i d ] : h t t p : / / e x a m p l e . c o m / l o n g i s h / p a t h / t o / r e s o u r c e / h e r e " O p t i o n a l T i t l e H e r e " LinkdefinitionsareonlyusedforcreatinglinksduringMarkdownprocessing,andare strippedfromyourdocumentintheHTMLoutput. Linkdefinitionnamesmayconsistofletters,numbers,spaces,andpunctuationbut theyarenotcasesensitive.E.g.thesetwolinks: [ l i n k t e x t ] [ a ] [ l i n k t e x t ] [ A ] areequivalent. Theimplicitlinknameshortcutallowsyoutoomitthenameofthelink,inwhichcasethe linktextitselfisusedasthename.Justuseanemptysetofsquarebracketse.g.,to linkthewordGoogletothegoogle.comwebsite,youcouldsimplywrite: [ G o o g l e ] [ ]

daringfireball.net/projects/markdown/syntax#header

12/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

Andthendefinethelink: [ G o o g l e ] : h t t p : / / g o o g l e . c o m / Becauselinknamesmaycontainspaces,thisshortcutevenworksformultiplewordsin thelinktext: V i s i t [ D a r i n g F i r e b a l l ] [ ] f o r m o r e i n f o r m a t i o n . Andthendefinethelink: [ D a r i n g F i r e b a l l ] : h t t p : / / d a r i n g f i r e b a l l . n e t / LinkdefinitionscanbeplacedanywhereinyourMarkdowndocument.Itendtoputthem immediatelyaftereachparagraphinwhichtheyreused,butifyouwant,youcanput themallattheendofyourdocument,sortoflikefootnotes. Heresanexampleofreferencelinksinaction: I g e t 1 0 t i m e s m o r e t r a f f i c f r o m [ G o o g l e ] [ 1 ] t h a n f r o m [ Y a h o o ] [ 2 ] o r [ M S N ] [ 3 ] . [ 1 ] : h t t p : / / g o o g l e . c o m / " G o o g l e " [ 2 ] : h t t p : / / s e a r c h . y a h o o . c o m / " Y a h o o S e a r c h " [ 3 ] : h t t p : / / s e a r c h . m s n . c o m / " M S N S e a r c h " Usingtheimplicitlinknameshortcut,youcouldinsteadwrite: I g e t 1 0 t i m e s m o r e t r a f f i c f r o m [ G o o g l e ] [ ] t h a n f r o m [ Y a h o o ] [ ] o r [ M S N ] [ ] . [ g o o g l e ] : h t t p : / / g o o g l e . c o m / " G o o g l e " [ y a h o o ] : h t t p : / / s e a r c h . y a h o o . c o m / " Y a h o o S e a r c h " [ m s n ] : h t t p : / / s e a r c h . m s n . c o m / " M S N S e a r c h " BothoftheaboveexampleswillproducethefollowingHTMLoutput: < p > I g e t 1 0 t i m e s m o r e t r a f f i c f r o m < a h r e f = " h t t p : / / g o o g l e . c o m / " t i t l e = " G o o g l e " > G o o g l e < / a > t h a n f r o m < a h r e f = " h t t p : / / s e a r c h . y a h o o . c o m / " t i t l e = " Y a h o o S e a r c h " > Y a h o o < / a > o r < a h r e f = " h t t p : / / s e a r c h . m s n . c o m / " t i t l e = " M S N S e a r c h " > M S N < / a > . < / p > Forcomparison,hereisthesameparagraphwrittenusingMarkdownsinlinelinkstyle: I g e t 1 0 t i m e s m o r e t r a f f i c f r o m [ G o o g l e ] ( h t t p : / / g o o g l e . c o m / " G o o g l e " ) t h a n f r o m [ Y a h o o ] ( h t t p : / / s e a r c h . y a h o o . c o m / " Y a h o o S e a r c h " ) o r [ M S N ] ( h t t p : / / s e a r c h . m s n . c o m / " M S N S e a r c h " ) . Thepointofreferencestylelinksisnotthattheyreeasiertowrite.Thepointisthatwith referencestylelinks,yourdocumentsourceisvastlymorereadable.Comparetheabove examples:usingreferencestylelinks,theparagraphitselfisonly81characterslong

daringfireball.net/projects/markdown/syntax#header

13/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

withinlinestylelinks,its176charactersandasrawHTML,its234characters.Inthe rawHTML,theresmoremarkupthanthereistext. WithMarkdownsreferencestylelinks,asourcedocumentmuchmorecloselyresembles thefinaloutput,asrenderedinabrowser.Byallowingyoutomovethemarkuprelated metadataoutoftheparagraph,youcanaddlinkswithoutinterruptingthenarrativeflow ofyourprose.

EM PHASIS
Markdowntreatsasterisks(* )andunderscores(_ )asindicatorsofemphasis.Text wrappedwithone* or_ willbewrappedwithanHTML< e m > tagdouble* sor_ swill bewrappedwithanHTML< s t r o n g > tag.E.g.,thisinput: * s i n g l e a s t e r i s k s * _ s i n g l e u n d e r s c o r e s _ * * d o u b l e a s t e r i s k s * * _ _ d o u b l e u n d e r s c o r e s _ _ willproduce: < e m > s i n g l e a s t e r i s k s < / e m > < e m > s i n g l e u n d e r s c o r e s < / e m > < s t r o n g > d o u b l e a s t e r i s k s < / s t r o n g > < s t r o n g > d o u b l e u n d e r s c o r e s < / s t r o n g > Youcanusewhicheverstyleyoupreferthelonerestrictionisthatthesamecharacter mustbeusedtoopenandcloseanemphasisspan. Emphasiscanbeusedinthemiddleofaword: u n * f r i g g i n g * b e l i e v a b l e Butifyousurroundan* or_ withspaces,itllbetreatedasaliteralasteriskor underscore. Toproducealiteralasteriskorunderscoreatapositionwhereitwouldotherwisebe usedasanemphasisdelimiter,youcanbackslashescapeit: \ * t h i s t e x t i s s u r r o u n d e d b y l i t e r a l a s t e r i s k s \ *

daringfireball.net/projects/markdown/syntax#header

14/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

CODE
Toindicateaspanofcode,wrapitwithbacktickquotes(` ).Unlikeapreformattedcode block,acodespanindicatescodewithinanormalparagraph.Forexample: U s e t h e ` p r i n t f ( ) ` f u n c t i o n . willproduce: < p > U s e t h e < c o d e > p r i n t f ( ) < / c o d e > f u n c t i o n . < / p > Toincludealiteralbacktickcharacterwithinacodespan,youcanusemultiplebackticks astheopeningandclosingdelimiters: ` ` T h e r e i s a l i t e r a l b a c k t i c k ( ` ) h e r e . ` ` whichwillproducethis: < p > < c o d e > T h e r e i s a l i t e r a l b a c k t i c k ( ` ) h e r e . < / c o d e > < / p > Thebacktickdelimiterssurroundingacodespanmayincludespacesoneafterthe opening,onebeforetheclosing.Thisallowsyoutoplaceliteralbacktickcharactersat thebeginningorendofacodespan: A s i n g l e b a c k t i c k i n a c o d e s p a n : ` ` ` ` ` A b a c k t i c k d e l i m i t e d s t r i n g i n a c o d e s p a n : ` ` ` f o o ` ` ` willproduce: < p > A s i n g l e b a c k t i c k i n a c o d e s p a n : < c o d e > ` < / c o d e > < / p > < p > A b a c k t i c k d e l i m i t e d s t r i n g i n a c o d e s p a n : < c o d e > ` f o o ` < / c o d e > < / p > Withacodespan,ampersandsandanglebracketsareencodedasHTMLentities automatically,whichmakesiteasytoincludeexampleHTMLtags.Markdownwillturn this: P l e a s e d o n ' t u s e a n y ` < b l i n k > ` t a g s . into: < p > P l e a s e d o n ' t u s e a n y < c o d e > & l t b l i n k & g t < / c o d e > t a g s . < / p > Youcanwritethis: ` & # 8 2 1 2 ` i s t h e d e c i m a l e n c o d e d e q u i v a l e n t o f ` & m d a s h ` . toproduce: < p > < c o d e > & a m p # 8 2 1 2 < / c o d e > i s t h e d e c i m a l e n c o d e d

daringfireball.net/projects/markdown/syntax#header

15/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

e q u i v a l e n t o f < c o d e > & a m p m d a s h < / c o d e > . < / p >

IM AGES
Admittedly,itsfairlydifficulttodeviseanaturalsyntaxforplacingimagesintoaplain textdocumentformat. Markdownusesanimagesyntaxthatisintendedtoresemblethesyntaxforlinks, allowingfortwostyles:inlineandreference. Inlineimagesyntaxlookslikethis: ! [ A l t t e x t ] ( / p a t h / t o / i m g . j p g ) ! [ A l t t e x t ] ( / p a t h / t o / i m g . j p g " O p t i o n a l t i t l e " ) Thatis: Anexclamationmark:! followedbyasetofsquarebrackets,containingthea l t attributetextforthe image followedbyasetofparentheses,containingtheURLorpathtotheimage,and anoptionalt i t l e attributeenclosedindoubleorsinglequotes. Referencestyleimagesyntaxlookslikethis: ! [ A l t t e x t ] [ i d ] Whereidisthenameofadefinedimagereference.Imagereferencesaredefined usingsyntaxidenticaltolinkreferences: [ i d ] : u r l / t o / i m a g e " O p t i o n a l t i t l e a t t r i b u t e " Asofthiswriting,Markdownhasnosyntaxforspecifyingthedimensionsofanimageif thisisimportanttoyou,youcansimplyuseregularHTML< i m g > tags.

MISCELLANEOU S

AUT OM AT ICL INKS

MarkdownsupportsashortcutstyleforcreatingautomaticlinksforURLsandemail

daringfireball.net/projects/markdown/syntax#header

16/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

addresses:simplysurroundtheURLoremailaddresswithanglebrackets.Whatthis meansisthatifyouwanttoshowtheactualtextofaURLoremailaddress,andalso haveitbeaclickablelink,youcandothis: < h t t p : / / e x a m p l e . c o m / > Markdownwillturnthisinto: < a h r e f = " h t t p : / / e x a m p l e . c o m / " > h t t p : / / e x a m p l e . c o m / < / a > Automaticlinksforemailaddressesworksimilarly,exceptthatMarkdownwillalso performabitofrandomizeddecimalandhexentityencodingtohelpobscureyour addressfromaddressharvestingspambots.Forexample,Markdownwillturnthis: < a d d r e s s @ e x a m p l e . c o m > intosomethinglikethis: < a h r e f = " & # x 6 D & # x 6 1 i & # x 6 C & # x 7 4 & # x 6 F : & # x 6 1 & # x 6 4 & # x 6 4 & # x 7 2 & # x 6 5 & # 1 1 5 & # 1 1 5 & # 6 4 & # 1 0 1 & # 1 2 0 & # x 6 1 & # 1 0 9 & # x 7 0 & # x 6 C e & # x 2 E & # 9 9 & # 1 1 1 & # 1 0 9 " > & # x 6 1 & # x 6 4 & # x 6 4 & # x 7 2 & # x 6 5 & # 1 1 5 & # 1 1 5 & # 6 4 & # 1 0 1 & # 1 2 0 & # x 6 1 & # 1 0 9 & # x 7 0 & # x 6 C e & # x 2 E & # 9 9 & # 1 1 1 & # 1 0 9 < / a > whichwillrenderinabrowserasaclickablelinktoaddress@example.com. (Thissortofentityencodingtrickwillindeedfoolmany,ifnotmost,addressharvesting bots,butitdefinitelywontfoolallofthem.Itsbetterthannothing,butanaddress publishedinthiswaywillprobablyeventuallystartreceivingspam.)

BACKSL ASHESCAPES
Markdownallowsyoutousebackslashescapestogenerateliteralcharacterswhich wouldotherwisehavespecialmeaninginMarkdownsformattingsyntax.Forexample,if youwantedtosurroundawordwithliteralasterisks(insteadofanHTML< e m > tag),you canusebackslashesbeforetheasterisks,likethis: \ * l i t e r a l a s t e r i s k s \ * Markdownprovidesbackslashescapesforthefollowingcharacters: \ b a c k s l a s h ` b a c k t i c k * a s t e r i s k _ u n d e r s c o r e { } c u r l y b r a c e s [ ] s q u a r e b r a c k e t s ( ) p a r e n t h e s e s

daringfireball.net/projects/markdown/syntax#header

17/18

9/4/13

Daring Fireball: Markdown Syntax Documentation

# h a s h m a r k + p l u s s i g n m i n u s s i g n ( h y p h e n ) . d o t ! e x c l a m a t i o n m a r k

Search

ShopatAmazon.comandsupportDaringFireball LinkedList|DisplayPreferences Copyright20022013TheDaringFireballCompanyLLC.

daringfireball.net/projects/markdown/syntax#header

18/18