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