Changes between Version 31 and Version 32 of MarkdownMacro

Timestamp:

May 28, 2021, 10:03:29 AM (3 years ago)

Author:

Cinc-th

Comment:

Added syntax description for some Markdown and Trac dialect

MarkdownMacro

@@ -7 +7 @@
 This macro implements John Gruber's [http://daringfireball.net/projects/markdown/ Markdown] lightweight plain text-to-HTML formatting syntax as a [WikiProcessors wiki processor] macro.
 
-Example of its usage:
+Example of its [#usage usage]:
 
 {{{
@@ -65 +65 @@
 == Installation
 
-First you need to install the [pypi:Markdown Python Markdown] package.
-Follow the instructions on the Web site.
+Easiest way is installation from source using PIP:
+{{{
+pip install https://trac-hacks.org/svn/markdownmacro/trunk
+}}}
+This takes care of the [pypi:Markdown Python Markdown] package which is automtically installed.
 
 General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.
@@ -88 +91 @@
 exclusive and should not be both enabled.
 
+== Usage
+The general [http://daringfireball.net/projects/markdown/syntax Markdown syntax] is supported by the macro. In addition the [https://python-markdown.github.io/extensions/extra/ Markdown extra] extension is enabled which brings support for [https://python-markdown.github.io/extensions/tables/ tables], [https://python-markdown.github.io/extensions/footnotes/ footnotes] and more.
+
+Some of Tracs syntax was added to Markdown so WikiProcessors, WikiMacros and ticket links can be used seamlessly.
+
+=== Basic usage
+The macro can only be used as a [WikiProcessors WikiProcessor].
+{{{
+{{{#!Markdown
+# A Header
+
+This is *all* Markdown.
+}}}
+}}}
+
+=== Links
+
+Since the full [http://daringfireball.net/projects/markdown/syntax Markdown syntax] is implemented links can be specified in different ways. Using a link section in your Markdown text holding all references may be especially useful for structuring the content.
+{{{
+{{{#!Markdown
+# Using links
+
+This is [an example](http://example.com/foo#section "Title") inline link.
+
+Link defined with [an id][id] somewhere in the text.
+
+Implicit links work: [Bar link][]
+
+Autolink: <http://example.com/foo>
+
+## Links below but not rendered
+
+[id]: <http://example.com/foo>  "Foo Title Here"
+
+[foo]: http://example.com/foo  "Foo Title Here"
+
+[Bar link]: http://example.com/bar  "Bar Title Here"
+
+}}}
+}}}
+For more visit the [http://daringfireball.net/projects/markdown/syntax Markdown syntax] page.
+
+=== Inline HTML
+
+HTML tags can be used whenever needed.
+{{{
+{{{#!Markdown
+# A Header
+
+This is *all* Markdown but HTML tags can be used when needed:
+
+<table>
+    <tr>
+        <td>Foo</td>
+    </tr>
+</table>
+
+}}}
+}}}
+
+Because the [https://python-markdown.github.io/extensions/md_in_html/ Markdown in HTML] extensions is enabled it is possible to wrap Markdown text in tags and still have the Markdown parsed.
+
+Note the attribute {{{markdown}}} in the following example. See [https://python-markdown.github.io/extensions/md_in_html/ Markdown in HTML] for possible values.
+{{{
+{{{#!Markdown
+# A Header
+
+<div style="border: 1px solid grey;" markdown="1">
+  This is Markdown _text_ with *formatting*.    
+</div>
+
+}}}
+}}}
+
+This can also be used with Trac features like WikiMacros:
+{{{
+{{{#!Markdown
+# A Header
+
+<div style="border: 1px solid grey;" markdown="1">
+  [[TracIni()]]    
+</div>
+
+}}}
+}}}
+ 
+=== !TracLinks
+**Note:** this is a Trac addition
+
+TracLinks are supported with the following syntax:
+{{{
+[Trac link specifier]
+}}}
+for example:
+{{{
+[ticket:2]
+
+[changeset:18323 Changest 18323]
+}}}
+Shortcut notations like {{{r18323}}} or {{{ticket:12000}}} are not working so alway add the brackets.
+
+=== Wiki links
+
+The Markdown [https://python-markdown.github.io/extensions/wikilinks/ WikiLinks syntax] is supported:
+
+{{{
+A link to [[WikiStart]].
+}}}
+
+In addition you may use TracLinks notation if you want to use another label.
+{{{
+Use TracLinks notation with [WikiStart Startpage].
+}}}
+**Note:** the second variant is a Trac addition
+
+=== Using !WikiProcessors
+
+**Note:** this is a Trac addition
+
+WikiProcessors can be used without any special escape syntax. Just add the processor to the Markdown text.
+{{{
+{{{#!Markdown
+# A Header
+
+This is *all* Markdown but Trac WikiProcessors can be used:
+
+{{{#!python
+def function():
+    foo = 1
+}}}
+
+{{{#!ini
+[section]
+foo = bar
+}}}
+
+}}}
+}}}
+
+=== Using !WikiMacros
+
+**Note:** this is a Trac addition
+
+Tracs WikiMacros can be used like with normal Trac wiki syntax.
+
+{{{
+{{{#!Markdown
+# A Header
+
+This is *all* Markdown but Trac WikiMacros can be used:
+
+[[TracIni()]]
+
+}}}
+}}}
+
 == Recent Changes