From daa2d46b567e67aa4578a5c26a7d92e4cf5abc81 Mon Sep 17 00:00:00 2001 From: ryneeverett Date: Thu, 3 Oct 2013 16:51:07 -0400 Subject: Issue #52 --- docs/extensions/extra.txt | 96 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) (limited to 'docs') diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt index d747496..6140647 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.txt @@ -41,3 +41,99 @@ therefore, not part of Python-Markdown Extra. If you really would like Extra to include additional extensions, we suggest creating your own clone of Extra under a different name (see the [Extension API](api.html)). + +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. + +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. + +
+This is *true* markdown text. +
+``` +#### Result: +``` +

This is true markdown text.

+
+

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. + +#### Complex Example: +``` +
+ +The text of the `Example` element. + +
+This text gets wrapped in `p` tags. +
+ +The tail of the `DefaultBlockMode` subelement. + +

+This text *is not* wrapped in additional `p` tags. +

+ +The tail of the `DefaultSpanMode` subelement. + +
+This `div` block is not wrapped in paragraph tags. +Note: Subelements are not required to have tail text. +
+ +

+This `p` block *is* foolishly wrapped in further paragraph tags. +

+ +The tail of the `BlockModeOverride` subelement. + +
+Raw html blocks may also be nested. +
+ +
+ +This text is after the markdown in html. +``` +#### Result: +``` +
+

The text of the Example element.

+
+

This text gets wrapped in p tags.

+
+

The tail of the DefaultBlockMode subelement.

+

+This text is not wrapped in additional p tags.

+

The tail of the DefaultSpanMode subelement.

+
+This div block is not wrapped in paragraph tags. +Note: Subelements are not required to have tail text.
+

+

This p block is foolishly wrapped in further paragraph tags.

+

+

The tail of the BlockModeOverride subelement.

+
+Raw html blocks may also be nested. +
+ +
+

This text is after the markdown in html.

+``` -- cgit v1.2.3