aboutsummaryrefslogtreecommitdiffstats
path: root/home_page.txt
diff options
context:
space:
mode:
Diffstat (limited to 'home_page.txt')
-rw-r--r--home_page.txt107
1 files changed, 83 insertions, 24 deletions
diff --git a/home_page.txt b/home_page.txt
index 9054254..89a9cc4 100644
--- a/home_page.txt
+++ b/home_page.txt
@@ -24,8 +24,12 @@ If you find something missing, [submit a bug report](http://sourceforge.net/trac
[Download](http://sourceforge.net/project/showfiles.php?group_id=153041)
the zip file and extract the files. If you want to install markdown
-as as a module into your python tree, run "python setup.py install"
-from a directory where you unzip the files.
+as as a module into your python tree, run "sudo python setup.py
+install" from a directory where you unzip the files. (You typically
+need to be root to install modules this way - hence use of "sudo". If
+you don't have root access, it probably doesn't make sense for you to
+"install" markdown this way - just put the markdown.py file somewhere
+and make sure that directory is in your path later.)
<a name="Commandline"></a>
<h3 class="title">Command Line Usage</h3>
@@ -53,6 +57,7 @@ command line options to specify encoding or to run extensions.
encoding for input and output files
-q, --quiet suppress all messages
-v, --verbose print info messages
+ -s, --safe same mode (strip user's HTML tag)
--noisy print debug messages
-x EXTENSION, --extension=EXTENSION
load extension EXTENSION
@@ -72,7 +77,7 @@ pass them in as well:
<a name="Module"></a>
<h3 class="title">Using the Module</h3>
-To use it as markdown as a module:
+To use markdown as a module:
import markdown
html = markdown.markdown(your_text_string)
@@ -84,7 +89,8 @@ Alternatively, if you want to pass more options:
extensions=['footnotes'],
extension_configs= {'footnotes' :
('PLACE_MARKER','~~~~~~~~')}
- encoding='utf8')
+ encoding='utf8',
+ safe_mode = True)
return md.toString()
@@ -93,15 +99,10 @@ or, if you want to process multiple strings:
md = Markdown(text=None)
md.toString(text)
-Finally, if the extensions are fully compatible, you should be able to
-get a list of extensions and their config parameters:
-
- for x in md.getExtensions():
-
- print x.name
- print x.oneliner
- print x.getConfigInfo()
-
+Note that if you are using Markdown on a web system which will
+transform text provided by untrusted users, you may want to use
+"safe_mode=True" option (see above) which ensures that user's HTML tags are
+removed. (They can still create links using Markdown syntax.)
<a name="Extending"></a>
<h3 class="title">Writing Extensions</h3>
@@ -115,7 +116,7 @@ beginning. It is sufficient to write a class with a run() method that
takes a list of text lines as a parameter and returns the same or a
new list. An instance of the preprocessor can then be inserted into
the markdown pipeline. Preprocessor classes must extend
-markdown.Preprocessor.
+``markdown.Preprocessor``.
class SamplePreprocessor (markdown.Preprocessor) :
def run(self, lines) :
@@ -129,7 +130,7 @@ markdown.Preprocessor.
**Post-processors** operate on a NanoDom tree and run at the very end.
They need to implement a "run" method that takes a pointer to a NanoDom
-document. Postprocessor classes must extend markdown.Postprocessor.
+document. Postprocessor classes must extend ``markdown.Postprocessor``.
class SamplePostprocessor (markdown.Postprocessor):
def run(self, doc) :
@@ -163,7 +164,7 @@ be doing is inserting preprocessors, postprocessors and patterns into
the markdown pipeline:
- def extendMarkdown(self, md, md_globals) :
+ def extendMarkdown(self, md, md_globals) :
self.md = md
@@ -177,8 +178,8 @@ the markdown pipeline:
If the extension uses any parameters that the use may want to change,
they should be stored in self.config in the following format:
- self.config = {parameter_1_name : [value1, description1],
- parameter_2_name : [value2, description2] }
+ self.config = {parameter_1_name : [value1, description1],
+ parameter_2_name : [value2, description2] }
When stored this way the config parameters can be over-riden from the
command line or at the time Markdown is instantiated:
@@ -199,12 +200,17 @@ returns an instance of the extension. E.g.:
def makeExtension(configs=None) :
return FootnoteExtension(configs=configs)
-See the implementation of footnote support (mdx_footnotes.py) for an
-example of using all three in combination to provide reasonably
-complex additional functionality. (I use a pre-processor to collect
-footnote definitions, an inline pattern to handle uses of footnotes
-inside the text and a post-processor to attach the HTML of the actual
-footnotes at the end of the document)
+See the implementation of footnote support distributed with the
+markdown script (mdx_footnotes.py) for an example of using all three
+in combination to provide reasonably complex additional functionality.
+(I use a pre-processor to collect footnote definitions, an inline
+pattern to handle uses of footnotes inside the text and a
+post-processor to attach the HTML of the actual footnotes at the end
+of the document) The RSS extension (mdx_rss.py, also included), which
+generates an RSS file from markdown source is a simpler extension but
+provides an example of extending markdown to generate arbitrary XML
+rather than HTML.
+
Other extensions:
@@ -218,6 +224,59 @@ Other extensions:
* [WikiLinks](http://achinghead.com/archives/67/adding-wikilinks-to-markdown-in-python/)
by Waylan Limberg (not yet upgraded)
+
+<a name="Django"></a>
+<h3 class="title">Using Markdown with Django</h3>
+
+Install markdown and make sure it is in your path.
+Include 'django.contrib.markup' in INSTALLED_APPS in your settings.py.
+You will then need to load the markup module in a template:
+
+ {% load markup %}
+
+After that, you should be able to use markdown filter in that template
+as follows by putting "|markdown" after a variable, e.g.:
+
+ {{ post.body|markdown }}
+
+If you want to use markdown with extensions or want an option of
+disabling HTML (e.g., in comments) edit
+django/contrib/markup/templatetags/markup.py file in your django tree
+replacing the definition of markdown() function with the following:
+
+ def markdown(value, arg=''):
+
+ try:
+ import markdown
+ except ImportError:
+ if settings.DEBUG:
+ raise (template.TemplateSyntaxError,
+ "Error in {% markdown %} filter: "
+ + "The markdown library isn't installed.")
+ else :
+ from django.utils.html import escape, linebreaks
+ return linebreaks(escape(value))
+ else:
+ extensions=arg.split(",")
+ if len(extensions) > 0 and extensions[0] == "safe" :
+ extensions = extensions[1:]
+ safe_mode = True
+ else :
+ safe_mode = False
+ return markdown.markdown(value, extensions, safe_mode=safe_mode)
+
+(This code snippet has been adapted from one proposed by [Waylan
+Limberg](http://achinghead.com/).)
+
+You should then be able to load extensions by listing them in quotes
+separated by comas:
+
+ {{ post.body|markdown:"imagelinks,footnotes" }}
+
+If you want to disable HTML, include "safe" as the first argument:
+
+ {{ post.body|markdown:"safe" }}
+
<a name="Credits"></a>
<h3 class="title">Credits</h3>