` tags in the HTML output. For example, this input:
378 |
379 | * Bird
380 | * Magic
381 |
382 | will turn into:
383 |
384 |
442 |
443 |
444 | It's worth noting that it's possible to trigger an ordered list by
445 | accident, by writing something like this:
446 |
447 | 1986. What a great season.
448 |
449 | In other words, a *number-period-space* sequence at the beginning of a
450 | line. To avoid this, you can backslash-escape the period:
451 |
452 | 1986\. What a great season.
453 |
454 |
455 |
456 | Code Blocks
457 |
458 | Pre-formatted code blocks are used for writing about programming or
459 | markup source code. Rather than forming normal paragraphs, the lines
460 | of a code block are interpreted literally. Markdown wraps a code block
461 | in both `` and `` tags.
462 |
463 | To produce a code block in Markdown, simply indent every line of the
464 | block by at least 4 spaces or 1 tab. For example, given this input:
465 |
466 | This is a normal paragraph:
467 |
468 | This is a code block.
469 |
470 | Markdown will generate:
471 |
472 | This is a normal paragraph:
473 |
474 | This is a code block.
475 |
476 |
477 | One level of indentation -- 4 spaces or 1 tab -- is removed from each
478 | line of the code block. For example, this:
479 |
480 | Here is an example of AppleScript:
481 |
482 | tell application "Foo"
483 | beep
484 | end tell
485 |
486 | will turn into:
487 |
488 | Here is an example of AppleScript:
489 |
490 | tell application "Foo"
491 | beep
492 | end tell
493 |
494 |
495 | A code block continues until it reaches a line that is not indented
496 | (or the end of the article).
497 |
498 | Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
499 | are automatically converted into HTML entities. This makes it very
500 | easy to include example HTML source code using Markdown -- just paste
501 | it and indent it, and Markdown will handle the hassle of encoding the
502 | ampersands and angle brackets. For example, this:
503 |
504 |
507 |
508 | will turn into:
509 |
510 | <div class="footer">
511 | © 2004 Foo Corporation
512 | </div>
513 |
514 |
515 | Regular Markdown syntax is not processed within code blocks. E.g.,
516 | asterisks are just literal asterisks within a code block. This means
517 | it's also easy to use Markdown to write about Markdown's own syntax.
518 |
519 |
520 |
521 | Horizontal Rules
522 |
523 | You can produce a horizontal rule tag (`
`) by placing three or
524 | more hyphens, asterisks, or underscores on a line by themselves. If you
525 | wish, you may use spaces between the hyphens or asterisks. Each of the
526 | following lines will produce a horizontal rule:
527 |
528 | * * *
529 |
530 | ***
531 |
532 | *****
533 |
534 | - - -
535 |
536 | ---------------------------------------
537 |
538 | _ _ _
539 |
540 |
541 | * * *
542 |
543 | Span Elements
544 |
545 | Links
546 |
547 | Markdown supports two style of links: *inline* and *reference*.
548 |
549 | In both styles, the link text is delimited by [square brackets].
550 |
551 | To create an inline link, use a set of regular parentheses immediately
552 | after the link text's closing square bracket. Inside the parentheses,
553 | put the URL where you want the link to point, along with an *optional*
554 | title for the link, surrounded in quotes. For example:
555 |
556 | This is [an example](http://example.com/ "Title") inline link.
557 |
558 | [This link](http://example.net/) has no title attribute.
559 |
560 | Will produce:
561 |
562 | This is
563 | an example inline link.
564 |
565 | This link has no
566 | title attribute.
567 |
568 | If you're referring to a local resource on the same server, you can
569 | use relative paths:
570 |
571 | See my [About](/about/) page for details.
572 |
573 | Reference-style links use a second set of square brackets, inside
574 | which you place a label of your choosing to identify the link:
575 |
576 | This is [an example][id] reference-style link.
577 |
578 | You can optionally use a space to separate the sets of brackets:
579 |
580 | This is [an example] [id] reference-style link.
581 |
582 | Then, anywhere in the document, you define your link label like this,
583 | on a line by itself:
584 |
585 | [id]: http://example.com/ "Optional Title Here"
586 |
587 | That is:
588 |
589 | * Square brackets containing the link identifier (optionally
590 | indented from the left margin using spaces or tabs);
591 | * followed by a colon;
592 | * followed by one or more spaces (or tabs);
593 | * followed by the URL for the link;
594 | * optionally followed by a title attribute for the link, enclosed
595 | in double or single quotes.
596 |
597 | The link URL may, optionally, be surrounded by angle brackets:
598 |
599 | [id]: "Optional Title Here"
600 |
601 | You can put the title attribute on the next line and use extra spaces
602 | or tabs for padding, which tends to look better with longer URLs:
603 |
604 | [id]: http://example.com/longish/path/to/resource/here
605 | "Optional Title Here"
606 |
607 | Link definitions are only used for creating links during Markdown
608 | processing, and are stripped from your document in the HTML output.
609 |
610 | Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
611 |
612 | [link text][a]
613 | [link text][A]
614 |
615 | are equivalent.
616 |
617 | The *implicit link name* shortcut allows you to omit the name of the
618 | link, in which case the link text itself is used as the name.
619 | Just use an empty set of square brackets -- e.g., to link the word
620 | "Google" to the google.com web site, you could simply write:
621 |
622 | [Google][]
623 |
624 | And then define the link:
625 |
626 | [Google]: http://google.com/
627 |
628 | Because link names may contain spaces, this shortcut even works for
629 | multiple words in the link text:
630 |
631 | Visit [Daring Fireball][] for more information.
632 |
633 | And then define the link:
634 |
635 | [Daring Fireball]: http://daringfireball.net/
636 |
637 | Link definitions can be placed anywhere in your Markdown document. I
638 | tend to put them immediately after each paragraph in which they're
639 | used, but if you want, you can put them all at the end of your
640 | document, sort of like footnotes.
641 |
642 | Here's an example of reference links in action:
643 |
644 | I get 10 times more traffic from [Google] [1] than from
645 | [Yahoo] [2] or [MSN] [3].
646 |
647 | [1]: http://google.com/ "Google"
648 | [2]: http://search.yahoo.com/ "Yahoo Search"
649 | [3]: http://search.msn.com/ "MSN Search"
650 |
651 | Using the implicit link name shortcut, you could instead write:
652 |
653 | I get 10 times more traffic from [Google][] than from
654 | [Yahoo][] or [MSN][].
655 |
656 | [google]: http://google.com/ "Google"
657 | [yahoo]: http://search.yahoo.com/ "Yahoo Search"
658 | [msn]: http://search.msn.com/ "MSN Search"
659 |
660 | Both of the above examples will produce the following HTML output:
661 |
662 | I get 10 times more traffic from Google than from
664 | Yahoo
665 | or MSN.
666 |
667 | For comparison, here is the same paragraph written using
668 | Markdown's inline link style:
669 |
670 | I get 10 times more traffic from [Google](http://google.com/ "Google")
671 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
672 | [MSN](http://search.msn.com/ "MSN Search").
673 |
674 | The point of reference-style links is not that they're easier to
675 | write. The point is that with reference-style links, your document
676 | source is vastly more readable. Compare the above examples: using
677 | reference-style links, the paragraph itself is only 81 characters
678 | long; with inline-style links, it's 176 characters; and as raw HTML,
679 | it's 234 characters. In the raw HTML, there's more markup than there
680 | is text.
681 |
682 | With Markdown's reference-style links, a source document much more
683 | closely resembles the final output, as rendered in a browser. By
684 | allowing you to move the markup-related metadata out of the paragraph,
685 | you can add links without interrupting the narrative flow of your
686 | prose.
687 |
688 |
689 | Emphasis
690 |
691 | Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
692 | emphasis. Text wrapped with one `*` or `_` will be wrapped with an
693 | HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML
694 | `` tag. E.g., this input:
695 |
696 | *single asterisks*
697 |
698 | _single underscores_
699 |
700 | **double asterisks**
701 |
702 | __double underscores__
703 |
704 | will produce:
705 |
706 | single asterisks
707 |
708 | single underscores
709 |
710 | double asterisks
711 |
712 | double underscores
713 |
714 | You can use whichever style you prefer; the lone restriction is that
715 | the same character must be used to open and close an emphasis span.
716 |
717 | Emphasis can be used in the middle of a word:
718 |
719 | un*fucking*believable
720 |
721 | But if you surround an `*` or `_` with spaces, it'll be treated as a
722 | literal asterisk or underscore.
723 |
724 | To produce a literal asterisk or underscore at a position where it
725 | would otherwise be used as an emphasis delimiter, you can backslash
726 | escape it:
727 |
728 | \\*this text is surrounded by literal asterisks\\*
729 |
730 |
731 |
732 | Code
733 |
734 | To indicate a span of code, wrap it with backtick quotes (`` ` ``).
735 | Unlike a pre-formatted code block, a code span indicates code within a
736 | normal paragraph. For example:
737 |
738 | Use the `printf()` function.
739 |
740 | will produce:
741 |
742 | Use the printf() function.
743 |
744 | To include a literal backtick character within a code span, you can
745 | backslash escape it:
746 |
747 | `There is a literal backtick (\`) here.`
748 |
749 | Or, if you prefer, you can use multiple backticks as the opening and
750 | closing delimiters:
751 |
752 | ``There is a literal backtick (`) here.``
753 |
754 | Both of the previous two examples will produce this:
755 |
756 | There is a literal backtick (`) here.
757 |
758 | With a code span, ampersands and angle brackets are encoded as HTML
759 | entities automatically, which makes it easy to include example HTML
760 | tags. Markdown will turn this:
761 |
762 | Please don't use any `