From e0e42478aba41c5fa7abdbd897e85c97c89d4613 Mon Sep 17 00:00:00 2001 From: "Kyle J. McKay" Date: Mon, 9 Jan 2017 23:56:44 -0800 Subject: [PATCH] {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 --- basics.md | 42 ++++++++------ syntax.md | 160 +++++++++++++++++++++++++++++++++++------------------- 2 files changed, 129 insertions(+), 73 deletions(-) diff --git a/basics.md b/basics.md index 9215305..7bfb4ed 100644 --- a/basics.md +++ b/basics.md @@ -1,13 +1,14 @@ +================ Markdown: Basics ================ - +* _[Markdown Basics]( "Markdown Basics")_ +* [Syntax][] +* [License][] +- - - - - +------------------------------------------------ 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 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 -## Paragraphs, Headers, Blockquotes ## +-------------------------------- +Paragraphs, Headers, Blockquotes +-------------------------------- 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 @@ -102,8 +106,9 @@ Output: - -### Phrase Emphasis ### +~~~~~~~~~~~~~~~ +Phrase Emphasis +~~~~~~~~~~~~~~~ Markdown uses asterisks and underscores to indicate spans of emphasis. @@ -126,8 +131,9 @@ Output: Or, even, strike through instead.

- -## Lists ## +----- +Lists +----- Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`, `+`, and `-`) as list markers. These three markers are @@ -191,8 +197,9 @@ Output: - -### Links ### +~~~~~ +Links +~~~~~ Markdown supports two styles for creating links: *inline* and *reference*. With both styles, you use square brackets to delimit the @@ -248,7 +255,9 @@ Output: The New York Times.

-### Images ### +~~~~~~ +Images +~~~~~~ Image syntax is very much like link syntax. @@ -267,8 +276,9 @@ Both of the above examples produce the same output: alt text - -### Code ### +~~~~ +Code +~~~~ In a regular paragraph, you can create code span by wrapping text in backtick quotes. Any ampersands (`&`) and angle brackets (`<` or diff --git a/syntax.md b/syntax.md index d1fee7f..ba7978c 100644 --- a/syntax.md +++ b/syntax.md @@ -1,45 +1,50 @@ +================ Markdown: Syntax ================ - - - -* [Overview](#overview) - * [Philosophy](#philosophy) - * [Inline HTML](#html) - * [Automatic Escaping for Special Characters](#autoescape) -* [Block Elements](#block) - * [Paragraphs and Line Breaks](#p) - * [Headers](#header) - * [Blockquotes](#blockquote) - * [Lists](#list) - * [Code Blocks](#precode) - * [Horizontal Rules](#hr) -* [Span Elements](#span) - * [Links](#link) - * [Emphasis](#em) - * [Code](#code) - * [Images](#img) -* [Miscellaneous](#misc) - * [Backslash Escapes](#backslash) - * [Automatic Links](#autolink) +* [Markdown Basics][] +* _[Syntax]( "Markdown Syntax Documentation")_ +* [License][] + +- - - - - + +* [Overview][] + * [Philosophy][] + * [Inline HTML][] + * [Automatic Escaping for Special Characters][] +* [Block Elements][] + * [Paragraphs and Line Breaks][] + * [Headers][] + * [Blockquotes][] + * [Lists][] + * [Code Blocks][] + * [Horizontal Rules][] +* [Span Elements][] + * [Links][] + * [Emphasis][] + * [Code][] + * [Images][] +* [Miscellaneous][] + * [Backslash Escapes][] + * [Automatic Links][] **Note:** This document is itself written using Markdown; you 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 - - - - - -

Overview

+-------- +Overview +-------- -

Philosophy

+~~~~~~~~~~ +Philosophy +~~~~~~~~~~ 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. - -

Inline HTML

+~~~~~~~~~~~ +Inline HTML +~~~~~~~~~~~ Markdown's syntax is intended for one purpose: to be used as a 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 span-level tags. - -

Automatic Escaping for Special Characters

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Automatic Escaping for Special Characters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In HTML, there are two characters that demand special treatment: `<` 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 +-------------- -

Block Elements

- - -

Paragraphs and Line Breaks

+~~~~~~~~~~~~~~~~~~~~~~~~~~ +Paragraphs and Line Breaks +~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 @@ -206,8 +215,9 @@ work best -- and look better -- when you format them with hard breaks. [l]: #list - - +~~~~~~~ +Headers +~~~~~~~ Markdown supports two styles of headers, [Setext] [1] and [atx] [2]. @@ -261,7 +271,9 @@ determines the header level.) : ### This is an H3 ###### -

Blockquotes

+~~~~~~~~~~~ +Blockquotes +~~~~~~~~~~~ Markdown uses email-style `>` characters for blockquoting. If you're 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. -

Lists

+~~~~~ +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. - -

Code Blocks

+~~~~~~~~~~~ +Code Blocks +~~~~~~~~~~~ Pre-formatted code blocks are used for writing about programming or 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. - -

Horizontal Rules

+~~~~~~~~~~~~~~~~ +Horizontal Rules +~~~~~~~~~~~~~~~~ You can produce a horizontal rule tag (`
`) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you @@ -577,9 +593,14 @@ following lines will produce a horizontal rule: - - - - - -

Span Elements

- +------------- +Span Elements +------------- + +~~~~~ +Links +~~~~~ 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 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 subsections later in the document. +to subsections later in the document. Just like this document. 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. -

Emphasis

+~~~~~~~~ +Emphasis +~~~~~~~~ Markdown treats asterisks (`*`) and underscores (`_`) as indicators of emphasis. Text wrapped with one `*` or `_` will be wrapped with an @@ -790,7 +813,9 @@ escape it: \*this text is surrounded by literal asterisks\* -

Code

+~~~~ +Code +~~~~ To indicate a span of code, wrap it with backtick quotes (`` ` ``). Unlike a pre-formatted code block, a code span indicates code within a @@ -845,7 +870,9 @@ to produce: equivalent of &mdash;.

-

Images

+~~~~~~ +Images +~~~~~~ Admittedly, it's fairly difficult to devise a "natural" syntax for placing images into a plain text document format. @@ -885,18 +912,36 @@ use regular HTML `` tags. - - - - - -

Miscellaneous

+------------- +Miscellaneous +------------- - +~~~~~~~~~~~~~~~ +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: -Markdown will turn this into: +or this: + + http://example.com/ + +Markdown will turn that into: + + <http://example.com/> + +or this: http://example.com/ +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 Markdown will also perform a bit of randomized decimal and hex 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.) - -

Backslash Escapes

+~~~~~~~~~~~~~~~~~ +Backslash Escapes +~~~~~~~~~~~~~~~~~ Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown's