diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/extensions/code_hilite.txt | 11 | ||||
| -rw-r--r-- | docs/extensions/extra.txt | 12 | ||||
| -rw-r--r-- | docs/extensions/fenced_code_blocks.txt | 25 | ||||
| -rw-r--r-- | docs/extensions/footnotes.txt | 29 | ||||
| -rw-r--r-- | docs/extensions/wikilinks.txt | 5 |
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> - |