Permalink
Browse files

More (advanced) help on Markdown format - submitted by Dave Scotson

  • Loading branch information...
1 parent 3a5d4d8 commit 580b586bd8ab943ddeaae0bcaeea82bf0620621f thepurpleblob committed Feb 17, 2005
Showing with 140 additions and 0 deletions.
  1. +140 −0 lang/en/help/advanced_markdown.html
@@ -0,0 +1,140 @@
+<h2>Advanced Use of Markdown</h2>
+
+<div id="Main">
+
+<div class="article">
+<p>This section expands upon the basic information given in the section titled 'Enhancing Text With Markdown' to give those with special requirements the information needed to make the most of Markdown. If you don't recognise, or don't need, the formatting listed below then you should feel free to skip this section and return to it as and when needed.</p>
+
+<ul>
+
+<li><a href="#linebreaks">Line Breaks</a></li>
+<li><a href="#hr">Horizontal Rules</a></li>
+<li><a href="#image_links">Linked Images</a></li>
+<li><a href="#embedded">Embedding HTML</a></li>
+<li><a href="#preformatted">Pre-formatted Code</a></li>
+<li><a href="#special_char">Using Special Characters</a></li>
+<li><a href="#further">Further Reading</a></li>
+</ul>
+
+<h2><a id="linebreaks">Line Breaks</a></h2>
+
+<p>In some texts, for instance in poetry and verse, it is often necessary to insert line breaks. Trying to do so with the return key will not give the intended effect as by default the lines will be run together to create a paragraph.</p>
+
+<p><strong><code>The best laid schemes o' Mice an' Men,<br />
+Gang aft agley,<br />
+An' lea'e us nought but grief an' pain,<br />
+For promis'd joy!</code></strong></p>
+
+<p>The above input, using the enter key to insert line breaks will give the following output as such breaks are ignored:</p>
+
+<p>The best laid schemes o' Mice an' Men,
+Gang aft agley,
+An' lea'e us nought but grief an' pain,
+For promis'd joy!</p>
+
+<p>But by ending each line with two spaces you can force a line break as follows:</p>
+
+<p>The best laid schemes o' Mice an' Men,<br />
+Gang aft agley,<br />
+An' lea'e us nought but grief an' pain,<br />
+For promis'd joy! </p>
+
+<h2><a id="hr">Horizontal Rules</a></h2>
+
+<p>Horizontal rules can be created by placing three or more asterisks (*), hyphens (-) or underscores (_) on a line by themselves.</p>
+
+<p>This will work:</p>
+
+<p><strong><code>***</code></strong></p>
+
+<p>but you can add spaces or further characters to make it more obviously a section break in the text editing window e.g.</p>
+
+<p><strong><code>* * * * *</code></strong></p>
+
+<p><strong><code>-------------------------</code></strong></p>
+
+<p><strong><code>_ _ _ _ _</code></strong></p>
+
+<p>All of these methods give the exact same result:</p>
+
+<hr />
+
+<h2><a id="image_links">Hyperlinked Images</a></h2>
+
+<p>The Enhancing Text With Markdown document gives instructions for creating web links and inserting images. It may not be obvious that these can be combined to create images that are also clickable links.</p>
+
+<p><strong><code>[the google search engine][google]</code></strong></p>
+
+<p><strong><code>![the google logo][logo]</code></strong></p>
+
+<p>Above are a standard web link and image. By placing the image where the link text would be found you end up with this:</p>
+
+<p><strong><code>[![the google logo][logo]][google]</code></strong></p>
+
+<p>This line above, in combination with the following link definitions elsewhere in the document:</p>
+
+<p><strong><code>[logo]: http://www.google.com/images/logo.gif</code></strong><br />
+<strong><code>[google]: http://www.google.com/ "click to visit Google.com"</code></strong></p>
+
+<p>combine to produce the following clickable image link (with tooltip if you hover over it):</p>
+
+<p><a href="http://www.google.com/" title="click to visit Google.com"><img src="http://www.google.com/images/logo.gif" alt="the google logo" /></a></p>
+
+<p>An example of where this technique might be handy is in linking small 'thumbnail' images to downloads of the larger photos.</p>
+
+<h2><a id="embedded">Embedding HTML</a></h2>
+
+<p>If you are already proficient in HTML then there may be occasions when Markdown does not allow you as much control as you are used to. Luckily Markdown is designed for this eventuality and allows you to embed HTML directly within Markdown formatted text.</p>
+
+<p><strong><code>* &lt;small&gt;small text&lt;/small&gt;</code></strong><br />
+
+<strong><code>* &lt;big&gt;big text&lt;/big&gt;</code></strong> </p>
+
+<ul>
+<li><small>small text</small> </li>
+<li><big>big text</big> </li>
+</ul>
+
+<p>Note that the HTML markup co-exists with the Markdown code for bullet lists. This frees you from the mundane task of writing complex HTML for basic formatting features such as paragraphs and lists while still allowing you to access the full power of HTML in specific situations.</p>
+
+<h2><a id="preformatted">Displaying HTML or Preformatted Text</a></h2>
+
+<p>If, unlike in the section above, you wish the HTML you enter to be displayed exactly as you typed it, rather than processed as HTML then you can start each line with four space characters.</p>
+
+<pre><code>&lt;p&gt;A paragraph in &lt;b&gt;HTML&lt;/b&gt; displayed as code&lt;/p&gt;
+</code></pre>
+
+<p>This also works for displaying computer code:</p>
+
+<pre><code>print "Command-line arguments: (@ARGV)\n";
+</code></pre>
+
+<p>As this formatting is often used for computer program listings and other text which may plausibly contain the characters that Markdown uses to indicate different types of formatting, Markdown's formatting is switched off for these lines:</p>
+
+<pre><code>Normally this word would be **bold**.
+</code></pre>
+
+<p>To include such characters within normal text, see the section below.</p>
+
+<h2><a id="special_char">Using Special Characters</a></h2>
+
+<p>If you wish to use any of the special characters that trigger Markdown formatting without them being processed simply precede them with a backslash character (\). This is known as 'escaping' a character. The backslash is not displayed but the character immediately following it is shown, exactly as entered.</p>
+
+<p><strong><code>\*asterisks, not emphasis\*</code></strong></p>
+
+<p>becomes</p>
+
+<p>*asterisks, not emphasis*</p>
+
+<p>rather than</p>
+
+<p><strong><code>*emphasis, not asterisks*</code></strong></p>
+
+<p>which gives</p>
+
+<p><em>emphasis, not asterisks</em></p>
+
+<h2><a id="further">Further Reading</a></h2>
+
+<p>The Markdown system is not unique to Moodle, it is used in an ever increasing number of web publishing tools. You can find out more about it at <a href="http://daringfireball.net/projects/markdown/">http://daringfireball.net/projects/markdown/</a></p>
+</div></div>

0 comments on commit 580b586

Please sign in to comment.