From 1144e2a94cf3f78dedda0b88649ce789fb8d1edf Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Sun, 16 Feb 2014 14:41:13 -0500 Subject: Cleaned up some minor issues with recent changes to docs. --- docs/extensions/code_hilite.txt | 21 +++++++++++---------- docs/extensions/extra.txt | 7 ++++--- docs/extensions/fenced_code_blocks.txt | 5 +++++ docs/extensions/footnotes.txt | 6 +++--- docs/extensions/header_id.txt | 8 ++++---- docs/extensions/smarty.txt | 26 +++++++++++++++++++------- docs/extensions/toc.txt | 10 +++++----- docs/extensions/wikilinks.txt | 8 ++++---- 8 files changed, 55 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 2cdb123..f0648e1 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -32,7 +32,8 @@ language. When that fails, the code block will display as un-highlighted code. !!! Note The css and/or javascript is not included as part of this extension - but shall always be provided by the end user. + but must be provided by the end user. The Pygments project provides + default css styles which you may find to be a useful starting point. Syntax ------ @@ -90,9 +91,9 @@ Will result in: # 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. +Certain lines can be selected for emphasis with the colon syntax. When +using Pygments' default css styles, emphasized lines have a yellow background. +This is useful to direct the reader's attention to specific lines. :::python hl_lines="1 3" # This line is emphasized @@ -135,7 +136,7 @@ configuring extensions. The following options are provided to configure the output: -* **linenums**: +* **`linenums`**: Use line numbers. Possible values are `True` for yes, `False` for no and `None` for auto. Defaults to `None`. @@ -145,22 +146,22 @@ The following options are provided to configure the output: Using `False` will turn off all line numbers, even when using SheBangs (`#!`) for language identification. -* **guess_lang**: +* **`guess_lang`**: Automatic language detection. Defaults to `True`. Using `False` will prevent Pygments from guessing the language, and thus highlighting blocks only when you explicitly set the language. -* **css_class**: +* **`css_class`**: Set CSS class name for the wrapper `
` tag. Defaults to `codehilite`. -* **pygments_style**: +* **`pygments_style`**: Pygments HTML Formatter Style (ColorScheme). Defaults to `default`. !!! Note This is useful only when `noclasses` is set to `True`, otherwise the - CSS style shall be provided by the end user. + CSS styles must be provided by the end user. -* **noclasses**: +* **`noclasses`**: Use inline styles instead of CSS classes. Defaults to `False`. diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt index b90d1b0..ace801b 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.txt @@ -69,9 +69,10 @@ This is *true* markdown text. ### Nested Markdown Inside HTML BLocks 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. + +* 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 206f6da..bfb65d3 100644 --- a/docs/extensions/fenced_code_blocks.txt +++ b/docs/extensions/fenced_code_blocks.txt @@ -35,6 +35,11 @@ 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. +!!! warning + + Fenced Code Blocks are only supported at the document root level. + Therefore, they cannot be nested inside lists or blockquotes. + ### Language ### In addition to PHP Extra's syntax, you can define the language of the code diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt index a18fb06..0f86595 100644 --- a/docs/extensions/footnotes.txt +++ b/docs/extensions/footnotes.txt @@ -72,17 +72,17 @@ configuring extensions. The following options are provided to configure the output: -* **PLACE_MARKER**: +* **`PLACE_MARKER`**: A text string used to mark the position where the footnotes are rendered. Defaults to `///Footnotes Go Here///`. If the place marker text is not found in the document, the footnote definitions are placed at the end of the resulting HTML document. -* **UNIQUE_IDS**: +* **`UNIQUE_IDS`**: Whether to avoid collisions across multiple calls to `reset()`. Defaults to `False`. -* **BACKLINK_TEXT**: +* **`BACKLINK_TEXT`**: The text string that links from the footnote definition back to the position in the document. Defaults to `↩`. diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt index afa1fe1..90eac3b 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.txt @@ -43,7 +43,7 @@ configuring extensions. The following options are provided to configure the output: -* **level**: Base level for headers. +* **`level`**: Base level for headers. Default: `1` @@ -60,7 +60,7 @@ The following options are provided to configure the output:

Some Header

Next Level

' -* **forceid**: Force all headers to have an id. +* **`forceid`**: Force all headers to have an id. Default: `True` @@ -77,11 +77,11 @@ The following options are provided to configure the output:

Some Header

Header with ID

-* **separator**: Word separator. Character which replaces whitespace in id. +* **`separator`**: Word separator. Character which replaces whitespace in id. Default: `-` -* **slugify**: Callable to generate anchors. +* **`slugify`**: Callable to generate anchors. Default: `markdown.extensions.headerid.slugify` diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.txt index 3cef11a..b96b82e 100644 --- a/docs/extensions/smarty.txt +++ b/docs/extensions/smarty.txt @@ -13,13 +13,25 @@ Summary The SmartyPants extension converts ASCII dashes, quotes and ellipses to their HTML entity equivalents. -ASCII symbol | Unicode replacements ------------- | -------------------- -' | ‘ ’ -" | “ ” -\... | … -\-- | – --\-- | — +ASCII symbol | Replacements | HTML Entities +------------ | --------------- | ------------------- +' | ‘ ’ | `‘` `’` +" | “ ” | `“` `”` +\... | … | `…` +\-- | – | `–` +-\-- | — | `—` + +!!! note + This extension reimplements the Python [SmartyPants] + library by intregated it into the markdown parser. + While this does not provide any additional features, + it does offer a few advantages. Notably, it will not + try to work on highlighted code blocks (using the + [CodeHilite] Extension) like the third party library + has been known to do. + +[SmartyPants]: http://pythonhosted.org/smartypants/ +[CodeHilite]: code_hilite.html Usage ----- diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index d13aadb..4d2d3c0 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -52,7 +52,7 @@ configuring extensions. The following options are provided to configure the output: -* **marker**: +* **`marker`**: Text to find and replace with the Table of Contents. Defaults to `[TOC]`. @@ -69,20 +69,20 @@ The following options are provided to configure the output: >>> html = md.convert(text) >>> render_some_template(context={'body': html, 'toc': md.toc}) -* **slugify**: +* **`slugify`**: Callable to generate anchors based on header text. Defaults to a built in `slugify` method. The callable must accept one argument which contains the text content of the header and return a string which will be used as the anchor text. -* **title**: +* **`title`**: Title to insert in the Table of Contents' `
`. Defaults to `None`. -* **anchorlink**: +* **`anchorlink`**: Setting to `True` will cause the headers link to themselves. Default is `False`. -* **permalink**: +* **`permalink`**: Set to `True` to have this extension generate a Sphinx-style permanent links near the headers (for use with Sphinx stylesheets). diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt index ea694a8..795ebb4 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.txt @@ -58,19 +58,19 @@ the html class `wikilink`. The following options are provided to change the default behavior: -* **base_url**: String to append to beginning of URL. +* **`base_url`**: String to append to beginning of URL. Default: `'/'` -* **end_url**: String to append to end of URL. +* **`end_url`**: String to append to end of URL. Default: `'/'` -* **html_class**: CSS class. Leave blank for none. +* **`html_class`**: CSS class. Leave blank for none. Default: `'wikilink'` -* **build_url**: Callable which formats the URL from its parts. +* **`build_url`**: Callable which formats the URL from its parts. ### Examples ### -- cgit v1.2.3