aboutsummaryrefslogtreecommitdiffstats
path: root/docs/extensions
diff options
context:
space:
mode:
Diffstat (limited to 'docs/extensions')
-rw-r--r--docs/extensions/code_hilite.txt11
-rw-r--r--docs/extensions/extra.txt12
-rw-r--r--docs/extensions/fenced_code_blocks.txt25
-rw-r--r--docs/extensions/footnotes.txt29
-rw-r--r--docs/extensions/wikilinks.txt5
5 files changed, 64 insertions, 18 deletions
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
index ab09742..92f60f8 100644
--- a/docs/extensions/code_hilite.txt
+++ b/docs/extensions/code_hilite.txt
@@ -91,6 +91,17 @@ block contains and each one has a different result.
# Code goes here ...
+ Certain lines can be selected for emphasis with the colon syntax. By
+ default, emphasized lines have a yellow background. This is useful to
+ direct the reader's attention.
+
+ :::python hl_lines="1 3"
+ # This line is emphasized
+ # This line isn't
+ # This line is emphasized
+
+ (`hl_lines` is named for Pygments' "highlighted lines" option.)
+
* ###When No Language is Defined
CodeHilite is completely backward compatible so that if a code block is
diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt
index 6140647..0507e8f 100644
--- a/docs/extensions/extra.txt
+++ b/docs/extensions/extra.txt
@@ -47,12 +47,10 @@ Markdown Inside HTML Blocks
Unlike the other Extra features, this feature is build into the markdown core and is turned on when `extra` is enabled.
-The content of any block-level element can be Markdown-formatted simply by adding a `markdown` attribute to the opening tag. The markdown attribute will be stripped from the output, but all other attributes will be preserved.
+The content of any raw html block element can be Markdown-formatted simply by adding a `markdown` attribute to the opening tag. The markdown attribute will be stripped from the output, but all other attributes will be preserved.
If the markdown value is set to `1` (recommended) or any value other than `span` or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`,`td`,`th`,`legend`, and `address` elements skip block parsing while others do not. If the default is overrident by a value of `span`, *block parsing will be skipped* regardless of tag. If the default is overriden by a value of `block`, *block parsing will occur* regardless of tag.
-*An opening tag with the markdown attribute must start immediately on a line following a blank line.*
-
#### Simple Example:
```
This is *true* markdown text.
@@ -70,10 +68,10 @@ This is *true* markdown text.
```
### Nested Markdown Inside HTML BLocks
-Nested elements are more sensitive and must be used cautiously. Violation of the following will lead to unexpected behavior or unhandled exceptions.
- * Only block mode elements may have further elements nested within them.
- * The closing tag of inner elements must be followed by a blank line.
- * More than one level of nesting is not supported (i.e., elements nested within elements nested within elements). This feature is not an alternative to templating.
+Nested elements are more sensitive and must be used cautiously. To avoid unexpected results:
+ * Only nest elements within block mode elements.
+ * Follow the closing tag of inner elements with a blank line.
+ * Only have one level of nesting.
#### Complex Example:
```
diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt
index c54c5bd..0148c80 100644
--- a/docs/extensions/fenced_code_blocks.txt
+++ b/docs/extensions/fenced_code_blocks.txt
@@ -35,6 +35,8 @@ Fenced code blocks can have a blank line as the first and/or last line of a
code block and they can also come immediately after a list item without becoming
part of the list.
+### Language
+
In addition to PHP Extra's syntax, you can define the language of the code
block for use by syntax highlighters etc. The language will be assigned as a
class attribute of the ``<code>`` element in the output. Therefore, you should
@@ -66,6 +68,29 @@ The above will output:
[Github]: http://github.github.com/github-flavored-markdown/
+### Emphasized Lines
+
+If [Pygments][] is installed, this extension can emphasize certain lines of
+code. By default, emphasized lines have a yellow background. This is useful to
+direct the reader's attention. The lines can be specified with PHP Extra's
+syntax:
+
+ ~~~~{.python hl_lines="1 3"}
+ # This line is emphasized
+ # This line isn't
+ # This line is emphasized
+
+... or with GitHub's:
+
+ ```python hl_lines="1 3"
+ # This line is emphasized
+ # This line isn't
+ # This line is emphasized
+
+(`hl_lines` is named for Pygments' "highlighted lines" option.)
+
+[Pygments]: http://pygments.org/
+
Usage
-----
diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt
index 1d6593c..e06344b 100644
--- a/docs/extensions/footnotes.txt
+++ b/docs/extensions/footnotes.txt
@@ -26,17 +26,30 @@ the output.
Example:
- Footnotes[^1] have a label[^label] and a definition[^!DEF].
+ Footnotes[^1] have a label[^@#$%] and the footnote's content.
- [^1]: This is a footnote
- [^label]: A footnote on "label"
- [^!DEF]: The definition of a footnote.
+ [^1]: This is a footnote's content.
+ [^@#$%]: A footnote on the label: "@#$%".
-A footnote definition may contain multiple lines, paragraphs, code blocks,
-blockquotes and most any other markdown syntax. The additional line simply
-must be indented at least an additional four spaces.
+A footnote label must start with a caret `^` and may contain any inline text
+(including spaces) between a set of square brackets `[]`. Only the first
+caret has any special meaning.
- [^1]: The first paragraph of the definition.
+A footnote's content must start with the label followed by a colon and at least
+one space. The label used to define the content must exactly match the label used
+in the body (including capitalization and whitespace). The content would then
+follow the label either on the same line or on the next line. The content may
+contain multiple lines, paragraphs, code blocks, blockquotes and most any other
+markdown syntax. The additional lines must be indented one level (four spaces or
+one tab).
+
+When working with multiple blocks, it may be helpful to start the content on a
+separate line from the label which defines the content. This way the entire block
+is indented consistently and any errors are more easily discernible by the author.
+
+
+ [^1]:
+ The first paragraph of the definition.
Paragraph two of the definition.
diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt
index 5cfdb77..ca36d17 100644
--- a/docs/extensions/wikilinks.txt
+++ b/docs/extensions/wikilinks.txt
@@ -49,7 +49,7 @@ Usage
From the Python interpreter:
>>> text = "Some text with a [[WikiLink]]."
- >>> html = markdown.markdown(text, ['wikilink'])
+ >>> html = markdown.markdown(text, ['wikilinks'])
The default behavior is to point each link to the document root of the current
domain and close with a trailing slash. Additionally, each link is assigned to
@@ -91,7 +91,7 @@ could also pass in a callable which must accept three arguments (``label``,
return url
md = markdown.Markdown(
- extensions=['wikilinks'],
+ extensions=['wikilinks],
extension_configs={'wikilinks' : [('build_url', my_url_builder)]}
)
@@ -147,4 +147,3 @@ This document:
would result in the following output (notice the blank `wiki_html_class`):
<p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.</p>
-