Public-Mirrors
/
markdown
mirror of https://github.com/mackyle/markdown.git
1
0
Fork 0
Code Releases Activity
Browse Source

{basics,syntax}.md: clean up formatting 

Clean up the formatting in baiscs and syntax to make it
more readable as a text document.

This is now possible by making use of the automatic
anchors for top-level headers and '~~~~~' style h3's.

Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
master
Kyle J. McKay 8 years ago
parent
4359f939a8
commit
e0e42478ab
2 changed files with 129 additions and 73 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 42
      basics.md
  2. 160
      syntax.md

42
basics.md
View File

@ -1,13 +1,14 @@
================
Markdown: Basics Markdown: Basics
================ ================
<ul id="ProjectSubmenu"> * _[Markdown Basics]( "Markdown Basics")_
<li><a class="selected" title="Markdown Basics">Basics</a></li> * [Syntax][]
<li><a href="syntax.html" title="Markdown Syntax Documentation">Syntax</a></li> * [License][]
<li><a href="LICENSE.html" title="License Information">License</a></li>
</ul>
- - - - -
------------------------------------------------
Getting the Gist of Markdown's Formatting Syntax Getting the Gist of Markdown's Formatting Syntax
------------------------------------------------ ------------------------------------------------
@ -25,11 +26,14 @@ and translate it to XHTML.
**Note:** This document is itself written using Markdown; you **Note:** This document is itself written using Markdown; you
can [see the source for it by adding `.md` to the URL] [src]. can [see the source for it by adding `.md` to the URL] [src].
[s]: syntax.html "Markdown Syntax" [syntax]: syntax.html "Markdown Syntax"
[license]: license.html "License Information"
[src]: basics.md [src]: basics.md
## Paragraphs, Headers, Blockquotes ## --------------------------------
Paragraphs, Headers, Blockquotes
--------------------------------
A paragraph is simply one or more consecutive lines of text, separated A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like by one or more blank lines. (A blank line is any line that looks like
@ -102,8 +106,9 @@ Output:
</blockquote> </blockquote>
~~~~~~~~~~~~~~~
### Phrase Emphasis ### Phrase Emphasis
~~~~~~~~~~~~~~~
Markdown uses asterisks and underscores to indicate spans of emphasis. Markdown uses asterisks and underscores to indicate spans of emphasis.
@ -126,8 +131,9 @@ Output:
Or, even, <strke>strike through instead</strike>.</p> Or, even, <strke>strike through instead</strike>.</p>
-----
## Lists ## Lists
-----
Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`, Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
`+`, and `-`) as list markers. These three markers are `+`, and `-`) as list markers. These three markers are
@ -191,8 +197,9 @@ Output:
</ul> </ul>
~~~~~
### Links ### Links
~~~~~
Markdown supports two styles for creating links: *inline* and Markdown supports two styles for creating links: *inline* and
*reference*. With both styles, you use square brackets to delimit the *reference*. With both styles, you use square brackets to delimit the
@ -248,7 +255,9 @@ Output:
<a href="http://www.nytimes.com/">The New York Times</a>.</p> <a href="http://www.nytimes.com/">The New York Times</a>.</p>
### Images ### ~~~~~~
Images
~~~~~~
Image syntax is very much like link syntax. Image syntax is very much like link syntax.
@ -267,8 +276,9 @@ Both of the above examples produce the same output:
<img src="/path/to/img.jpg" alt="alt text" title="Title" /> <img src="/path/to/img.jpg" alt="alt text" title="Title" />
~~~~
### Code ### Code
~~~~
In a regular paragraph, you can create code span by wrapping text in In a regular paragraph, you can create code span by wrapping text in
backtick quotes. Any ampersands (`&`) and angle brackets (`<` or backtick quotes. Any ampersands (`&`) and angle brackets (`<` or

160
syntax.md
View File

@ -1,45 +1,50 @@
================
Markdown: Syntax Markdown: Syntax
================ ================
<ul id="ProjectSubmenu"> * [Markdown Basics][]
<li><a href="basics.html" title="Markdown Basics">Basics</a></li> * _[Syntax]( "Markdown Syntax Documentation")_
<li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li> * [License][]
<li><a href="License.html" title="License Information">License</a></li>
</ul> - - - - -
* [Overview][]
* [Overview](#overview) * [Philosophy][]
* [Philosophy](#philosophy) * [Inline HTML][]
* [Inline HTML](#html) * [Automatic Escaping for Special Characters][]
* [Automatic Escaping for Special Characters](#autoescape) * [Block Elements][]
* [Block Elements](#block) * [Paragraphs and Line Breaks][]
* [Paragraphs and Line Breaks](#p) * [Headers][]
* [Headers](#header) * [Blockquotes][]
* [Blockquotes](#blockquote) * [Lists][]
* [Lists](#list) * [Code Blocks][]
* [Code Blocks](#precode) * [Horizontal Rules][]
* [Horizontal Rules](#hr) * [Span Elements][]
* [Span Elements](#span) * [Links][]
* [Links](#link) * [Emphasis][]
* [Emphasis](#em) * [Code][]
* [Code](#code) * [Images][]
* [Images](#img) * [Miscellaneous][]
* [Miscellaneous](#misc) * [Backslash Escapes][]
* [Backslash Escapes](#backslash) * [Automatic Links][]
* [Automatic Links](#autolink)
**Note:** This document is itself written using Markdown; you **Note:** This document is itself written using Markdown; you
can [see the source for it by adding `.md` to the URL][src]. can [see the source for it by adding `.md` to the URL][src].
[b]: basics.html "Markdown Basics" [markdown basics]: basics.html "Markdown Basics"
[license]: license.html "License Information"
[src]: syntax.md [src]: syntax.md
- - - - - - - - - -
<h2 id="overview">Overview</h2> --------
Overview
--------
<h3 id="philosophy">Philosophy</h3> ~~~~~~~~~~
Philosophy
~~~~~~~~~~
Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
@ -66,8 +71,9 @@ blockquotes look like quoted passages of text, assuming you've ever
used email. used email.
~~~~~~~~~~~
<h3 id="html">Inline HTML</h3> Inline HTML
~~~~~~~~~~~
Markdown's syntax is intended for one purpose: to be used as a Markdown's syntax is intended for one purpose: to be used as a
format for *writing* for the web. format for *writing* for the web.
@ -117,8 +123,9 @@ link or image syntax, go right ahead.
Unlike block-level HTML tags, Markdown syntax *is* processed within Unlike block-level HTML tags, Markdown syntax *is* processed within
span-level tags. span-level tags.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<h3 id="autoescape">Automatic Escaping for Special Characters</h3> Automatic Escaping for Special Characters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In HTML, there are two characters that demand special treatment: `<` In HTML, there are two characters that demand special treatment: `<`
and `&`. Left angle brackets are used to start tags; ampersands are and `&`. Left angle brackets are used to start tags; ampersands are
@ -176,11 +183,13 @@ and `&` in your example code needs to be escaped.)
- - - - - - - - - -
--------------
Block Elements
--------------
<h2 id="block">Block Elements</h2> ~~~~~~~~~~~~~~~~~~~~~~~~~~
Paragraphs and Line Breaks
~~~~~~~~~~~~~~~~~~~~~~~~~~
<h3 id="p">Paragraphs and Line Breaks</h3>
A paragraph is simply one or more consecutive lines of text, separated A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like a by one or more blank lines. (A blank line is any line that looks like a
@ -206,8 +215,9 @@ work best -- and look better -- when you format them with hard breaks.
[l]: #list [l]: #list
~~~~~~~
<h3 id="header">Headers</h3> Headers
~~~~~~~
Markdown supports two styles of headers, [Setext] [1] and [atx] [2]. Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
@ -261,7 +271,9 @@ determines the header level.) :
### This is an H3 ###### ### This is an H3 ######
<h3 id="blockquote">Blockquotes</h3> ~~~~~~~~~~~
Blockquotes
~~~~~~~~~~~
Markdown uses email-style `>` characters for blockquoting. If you're Markdown uses email-style `>` characters for blockquoting. If you're
familiar with quoting passages of text in an email message, then you familiar with quoting passages of text in an email message, then you
@ -311,7 +323,9 @@ example, with BBEdit, you can make a selection and choose Increase
Quote Level from the Text menu. Quote Level from the Text menu.
<h3 id="list">Lists</h3> ~~~~~
Lists
~~~~~
Markdown supports ordered (numbered) and unordered (bulleted) lists. Markdown supports ordered (numbered) and unordered (bulleted) lists.
@ -468,8 +482,9 @@ line. To avoid this, you can backslash-escape the period:
1986\. What a great season. 1986\. What a great season.
~~~~~~~~~~~
<h3 id="precode">Code Blocks</h3> Code Blocks
~~~~~~~~~~~
Pre-formatted code blocks are used for writing about programming or Pre-formatted code blocks are used for writing about programming or
markup source code. Rather than forming normal paragraphs, the lines markup source code. Rather than forming normal paragraphs, the lines
@ -556,8 +571,9 @@ asterisks are just literal asterisks within a code block. This means
it's also easy to use Markdown to write about Markdown's own syntax. it's also easy to use Markdown to write about Markdown's own syntax.
~~~~~~~~~~~~~~~~
<h3 id="hr">Horizontal Rules</h3> Horizontal Rules
~~~~~~~~~~~~~~~~
You can produce a horizontal rule tag (`<hr />`) by placing three or You can produce a horizontal rule tag (`<hr />`) by placing three or
more hyphens, asterisks, or underscores on a line by themselves. If you more hyphens, asterisks, or underscores on a line by themselves. If you
@ -577,9 +593,14 @@ following lines will produce a horizontal rule:
- - - - - - - - - -
<h2 id="span">Span Elements</h2>
<h3 id="link">Links</h3> -------------
Span Elements
-------------
~~~~~
Links
~~~~~
Markdown supports two style of links: *inline* and *reference*. Markdown supports two style of links: *inline* and *reference*.
@ -693,7 +714,7 @@ using either the setext-style or atx-style automatically have an
anchor id and link definition added for them provided there is not anchor id and link definition added for them provided there is not
already a previous definition with the same id. You can use this already a previous definition with the same id. You can use this
to place a table-of-contents at the top of the document that links to place a table-of-contents at the top of the document that links
to subsections later in the document. to subsections later in the document. Just like this document.
Here's an example of reference links in action: Here's an example of reference links in action:
@ -742,7 +763,9 @@ you can add links without interrupting the narrative flow of your
prose. prose.
<h3 id="em">Emphasis</h3> ~~~~~~~~
Emphasis
~~~~~~~~
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
emphasis. Text wrapped with one `*` or `_` will be wrapped with an emphasis. Text wrapped with one `*` or `_` will be wrapped with an
@ -790,7 +813,9 @@ escape it:
\*this text is surrounded by literal asterisks\* \*this text is surrounded by literal asterisks\*
<h3 id="code">Code</h3> ~~~~
Code
~~~~
To indicate a span of code, wrap it with backtick quotes (`` ` ``). To indicate a span of code, wrap it with backtick quotes (`` ` ``).
Unlike a pre-formatted code block, a code span indicates code within a Unlike a pre-formatted code block, a code span indicates code within a
@ -845,7 +870,9 @@ to produce:
equivalent of <code>&amp;mdash;</code>.</p> equivalent of <code>&amp;mdash;</code>.</p>
<h3 id="img">Images</h3> ~~~~~~
Images
~~~~~~
Admittedly, it's fairly difficult to devise a "natural" syntax for Admittedly, it's fairly difficult to devise a "natural" syntax for
placing images into a plain text document format. placing images into a plain text document format.
@ -885,18 +912,36 @@ use regular HTML `<img>` tags.
- - - - - - - - - -
<h2 id="misc">Miscellaneous</h2> -------------
Miscellaneous
-------------
<h3 id="autolink">Automatic Links</h3> ~~~~~~~~~~~~~~~
Automatic Links
~~~~~~~~~~~~~~~
Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this: Markdown supports a shortcut style for creating "automatic" links for URLs
and email addresses: simply surround the URL or email address with angle
brackets or don't. What this means is that if you want to show the actual text
of a URL or email address, and also have it be a clickable link, you can do:
<http://example.com/> <http://example.com/>
Markdown will turn this into: or this:
http://example.com/
Markdown will turn that into:
&lt;<a href="http://example.com/">http://example.com/</a>&gt;
or this:
<a href="http://example.com/">http://example.com/</a> <a href="http://example.com/">http://example.com/</a>
If Markdown is not quite grabbing the right link when it's not surrounded
by angle brackets then just add the angle brackets to avoid the guessing.
Automatic links for email addresses work similarly, except that Automatic links for email addresses work similarly, except that
Markdown will also perform a bit of randomized decimal and hex Markdown will also perform a bit of randomized decimal and hex
entity-encoding to help obscure your address from address-harvesting entity-encoding to help obscure your address from address-harvesting
@ -919,8 +964,9 @@ them. It's better than nothing, but an address published in this way
will probably eventually start receiving spam.) will probably eventually start receiving spam.)
~~~~~~~~~~~~~~~~~
<h3 id="backslash">Backslash Escapes</h3> Backslash Escapes
~~~~~~~~~~~~~~~~~
Markdown allows you to use backslash escapes to generate literal Markdown allows you to use backslash escapes to generate literal
characters which would otherwise have special meaning in Markdown's characters which would otherwise have special meaning in Markdown's

Write Preview
Loading…
Cancel
Save