diff options
| -rw-r--r-- | CHANGE_LOG.txt | 2 | ||||
| -rw-r--r-- | README.html | 91 | ||||
| -rw-r--r-- | README.txt | 98 | ||||
| -rw-r--r-- | home_page.txt | 338 | ||||
| -rw-r--r-- | sidebar.txt | 37 |
5 files changed, 191 insertions, 375 deletions
diff --git a/CHANGE_LOG.txt b/CHANGE_LOG.txt index 405a025..0d8b2d2 100644 --- a/CHANGE_LOG.txt +++ b/CHANGE_LOG.txt @@ -1,6 +1,8 @@ PYTHON MARKDOWN CHANGELOG ========================= +Dec 12, 2007: Updated docs. + Nov 29, 2007: Added support for images inside links. Also fixed a few bugs in the footnote extension. diff --git a/README.html b/README.html new file mode 100644 index 0000000..6d94e8e --- /dev/null +++ b/README.html @@ -0,0 +1,91 @@ +<h1><a href="http://freewisdom.org/projects/python-markdown">Python-Markdown</a></h1> +<p>This is a Python implementation of John Gruber's <a href="http://daringfireball.net/projects/markdown/">Markdown</a>. + It is almost completely compliant with the reference implementation, + though there are a few known issues. See <a href="http://www.freewisdom.org/projects/python-markdown/Features">Features</a> for information + on what exactly is supported and what is not. Additional features are + supported by the <a href="http://www.freewisdom.org/projects/python-markdown/Available_Extensions">Available Extensions</a>. +</p> + +<h2>Installation</h2> +<p>To install Python Markdown <a href="http://sourceforge.net/project/showfiles.php?group_id=153041">download</a> the zip file and extract the + files. If you want to install markdown as a module into your python + tree, run <code>sudo python setup.py install</code> from a directory where you + unzip the files. +</p> + +<h2>Command Line Usage</h2> +<p>To use markdown.py from the command line, run it as +</p> +<pre><code>python markdown.py <input_file> +</code></pre><p>or +</p> +<pre><code>python markdown.py <input_file> > <output_file> +</code></pre><p>For more details, use the <code>-h</code> or <code>--help</code> options from the command line + or read the <a href="http://www.freewisdom.org/projects/python-markdown/Command_Line">Command Line Docs</a> available online. +</p> + +<h2>Using as a Python Module</h2> +<p>To use markdown as a module: +</p> +<pre><code>import markdown +html = markdown.markdown(your_text_string) +</code></pre><p>For more details see the <a href="http://www.freewisdom.org/projects/python-markdown/Using_as_a_Module">Module Docs</a>. +</p> + +<h2>Support</h2> +<p>You may ask for help and discuss various other issues on the <a href="http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss">mailing list</a> and report bugs on the <a href="http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198">bug tracker</a>. +</p> + +<h2>Credits</h2> +<ul> + <li> + Most of the code currently in the module was written by <a href="http://www.freewisdom.org">Yuri Takhteyev</a> + while procrastinating from his Ph.D. + </li> + + <li> + The original version of this script was written by <a href="http://www.dwerg.net/">Manfred Stienstra</a>, + who is responsible for about a quarter of the code. + </li> + + <li> + Many recent bugs are being fixed by <a href="http://achinghead.com/">Waylan Limberg</a>. + </li> +</ul> +<p>Other contributions: +</p> +<ul> + <li> + Daniel Krech provided the setup.py script. + </li> + + <li> + G. Clark Haynes submitted a patch for indented lists. + </li> + + <li> + Tiago Cogumbreiro submitted an email autolink fix. + </li> + + <li> + Sergej Chodarev submitted a patch for treatment of <code><hr/></code> tags. + </li> + + <li> + Chris Clark submitted a patch to handle <code><mailto:...></code> syntax and a reg ex + for "smart" emphasis (ignoring underscores within a word). + </li> + + <li> + Steward Midwinter wrote command-line parser and cleaned up comments. + </li> + + <li> + Many other people helped by reporting bugs. + </li> +</ul> + +<h2>License</h2> +<p>The code is dual-licensed under <a href="http://www.gnu.org/copyleft/gpl.html)">GPL</a> and <a href="http://www.opensource.org/licenses/bsd-license.php">BSD License</a>. Other + licensing arrangements can be discussed. +</p>
\ No newline at end of file diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..b859924 --- /dev/null +++ b/README.txt @@ -0,0 +1,98 @@ +[Python-Markdown][] +=================== + +This is a Python implementation of John Gruber's [Markdown][]. +It is almost completely compliant with the reference implementation, +though there are a few known issues. See [Features][] for information +on what exactly is supported and what is not. Additional features are +supported by the [Available Extensions][]. + +[Python-Markdown]: http://freewisdom.org/projects/python-markdown +[Markdown]: http://daringfireball.net/projects/markdown/ +[Features]: http://www.freewisdom.org/projects/python-markdown/Features +[Available Extensions]: http://www.freewisdom.org/projects/python-markdown/Available_Extensions + + +Installation +------------ + +To install Python Markdown [download][] the zip file and extract the +files. If you want to install markdown as a module into your python +tree, run `sudo python setup.py install` from a directory where you +unzip the files. + +[download]: http://sourceforge.net/project/showfiles.php?group_id=153041 + + +Command Line Usage +------------------ + +To use markdown.py from the command line, run it as + + python markdown.py <input_file> + +or + + python markdown.py <input_file> > <output_file> + +For more details, use the `-h` or `--help` options from the command line +or read the [Command Line Docs][] available online. + +[Command Line Docs]: http://www.freewisdom.org/projects/python-markdown/Command_Line + + + +Using as a Python Module +------------------------ + +To use markdown as a module: + + import markdown + html = markdown.markdown(your_text_string) + +For more details see the [Module Docs][]. + +[Module Docs]: http://www.freewisdom.org/projects/python-markdown/Using_as_a_Module + +Support +------- + +You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][]. + +[mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss +[bug tracker]: http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198 + + +Credits +------- + +* Most of the code currently in the module was written by [Yuri Takhteyev][] + while procrastinating from his Ph.D. +* The original version of this script was written by [Manfred Stienstra][], + who is responsible for about a quarter of the code. +* Many recent bugs are being fixed by [Waylan Limberg][]. + +Other contributions: + +* Daniel Krech provided the setup.py script. +* G. Clark Haynes submitted a patch for indented lists. +* Tiago Cogumbreiro submitted an email autolink fix. +* Sergej Chodarev submitted a patch for treatment of `<hr/>` tags. +* Chris Clark submitted a patch to handle `<mailto:...>` syntax and a reg ex + for "smart" emphasis (ignoring underscores within a word). +* Steward Midwinter wrote command-line parser and cleaned up comments. +* Many other people helped by reporting bugs. + +[Yuri Takhteyev]: http://www.freewisdom.org +[Manfred Stienstra]: http://www.dwerg.net/ +[Waylan Limberg]: http://achinghead.com/ + + +License +------- + +The code is dual-licensed under [GPL][] and [BSD License][]. Other +licensing arrangements can be discussed. + +[GPL]: http://www.gnu.org/copyleft/gpl.html) +[BSD License]: http://www.opensource.org/licenses/bsd-license.php diff --git a/home_page.txt b/home_page.txt deleted file mode 100644 index 89a9cc4..0000000 --- a/home_page.txt +++ /dev/null @@ -1,338 +0,0 @@ -<?php include("markdown-header.php");?> - <div id="blog_entry"> - <div class="blogbody"> - -<a name="Summary"></a> -<h3 class="title">Summary</h3> - -This is a Python implementation of John Gruber's -[Markdown](http://daringfireball.net/projects/markdown/). -The current version of python-markdown implements all Markdown syntax -features and fully passes [Markdown Test Suite -1.0](http://six.pairlist.net/pipermail/markdown-discuss/2004-December/000909.html). It also supports footnotes (see [this -thread](http://six.pairlist.net/pipermail/markdown-discuss/2005-August/001480.html)) -and attributes (see [this -thread](http://six.pairlist.net/pipermail/markdown-discuss/2005-August/001486.html)). Python-Markdown defaults to ignoring middle-word emphasis through -underscore, but this it can be switched off. (See [this -thread](http://six.pairlist.net/pipermail/markdown-discuss/2005-October/001610.html) -for discussion.) - -If you find something missing, [submit a bug report](http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198) or send me an email (qaramazov-at-gmail.com). Better yet, send me a patch. - -<a name="Installation"></a> -<h3 class="title">Installation</h3> - -[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 "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> - -To use markdown.py by itself, run it as - - python markdown.py <input_file> - -or - - python markdown.py <input_file> > <output_file> - -If you are using Python 2.3 or higher, you can also use advanced -command line options to specify encoding or to run extensions. - - - $ python markdown.py - usage: markdown.py INPUTFILE [options] - - options: - -h, --help show this help message and exit - -f OUTPUT_FILE, --file=OUTPUT_FILE - write output to OUTPUT_FILE - -e ENCODING, --encoding=ENCODING - 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 - -For an extension to be ran this way it must be provided in a module -named ``mdx_{extensionname}.py`` which should be in your python path, -e.g. ``mdx_footnotes.py``. It can then be invoked as by name (the -part after "mdx_"): - - python markdown.py -x footnotes text_with_footnotes.txt output.html - -If the extension supports config options (see below), you can also -pass them in as well: - - python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" - -<a name="Module"></a> -<h3 class="title">Using the Module</h3> - -To use markdown as a module: - - import markdown - html = markdown.markdown(your_text_string) - -Alternatively, if you want to pass more options: - - import markdown - md = Markdown(text, - extensions=['footnotes'], - extension_configs= {'footnotes' : - ('PLACE_MARKER','~~~~~~~~')} - encoding='utf8', - safe_mode = True) - - return md.toString() - -or, if you want to process multiple strings: - - md = Markdown(text=None) - md.toString(text) - -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> - -The functionality of the script can be extended without changing the -code, by inserting additional pre-processors, post-processors or -inline patterns into Markdown's pipeline. - -**Pre-processors** operate on lines of source text and are run in the -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``. - - class SamplePreprocessor (markdown.Preprocessor) : - def run(self, lines) : - for i in range(len(lines)) : - if lines[i].startswith(SOMETHING) : - lines[i] = do_something(lines[i]) - - return lines - - md_instance.preprocessors.insert(SOME_INDEX, SamplePreprocessor()) - -**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``. - - class SamplePostprocessor (markdown.Postprocessor): - def run(self, doc) : - doc.documentElement.appendChild(doc.createElement("new")) - - - md_instance.postprocessors.insert(SOME_INDEX, SamplePostprocessor()) - -Finally, **inline patterns** can be added. Each inline pattern -includes a regular expression pattern and a method for turning a match -object into a DOM fragment - - class MyCustomPattern (markdown.Pattern) : - def handleMatch(self, m, doc) : - el = doc.createElement('custom') - el.setAttribute('stuff', m.group(3)) - return el - - new_pattern = MyCustomPattern(r'your regular expression here') - md_instance.inlinePatterns.insert(SOME_INDEX, new_pattern) - -Preprocessors, patterns and postprocessors need to then be wrapped -together into an extension, which should be implemented as a class -that extends markdown.Extension and should over-ride the -``extendMarkdown()`` method. ``extendMarkdown()`` is called during -markdown construction, giving the extension a pointer to the markdown -object (the ``md`` parameters) and markdown's global variables -(``md_globals``), which in theory gives the extension an option of -changing anything it cares to change. However, what it really should -be doing is inserting preprocessors, postprocessors and patterns into -the markdown pipeline: - - - def extendMarkdown(self, md, md_globals) : - - self.md = md - - # Insert a preprocessor before ReferencePreprocessor - index = md.preprocessors.index(md_globals['REFERENCE_PREPROCESSOR']) - preprocessor = FootnotePreprocessor(self) - preprocessor.md = md - md.preprocessors.insert(index, preprocessor) - - -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] } - -When stored this way the config parameters can be over-riden from the -command line or at the time Markdown is instantiated: - - markdown.py -x myextension(SOME_PARAM=2) inputfile.txt > output.txt - -Note that parameters should always be assumed to be set to string -values, and should be converted at the run time, e.g. - - i += int(self.getConfig("SOME_PARAM")) - -Each extension should ideally be placed in its own module starting -with ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must -provide a module-level function called ``makeExtensions`` that takes -as an optional parameter a list of configuration over-rides and -returns an instance of the extension. E.g.: - - def makeExtension(configs=None) : - return FootnoteExtension(configs=configs) - -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: - -* [Table-of-contents extension](extensions/mdx_toc.py) by Chris Clark - (inserts a table of contents), upgraded by - Yuri. - -* [Title extension](extensions/mdx_title.py) by Chris Clark (inserts a - title element) - -* [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> - -* The first version of this script was written by [Manfred - Stienstra](http://www.dwerg.net/), who is responsible for about - a quarter of the code. -* Daniel Krech provided the setup.py script. -* G. Clark Haynes submitted a patch for indented lists. -* Tiago Cogumbreiro submitted an email autolink fix. -* Sergej Chodarev submitted a patch for treatment of `<hr/>` tags. -* Chris Clark submitted a patch to handle `<mailto:...>` syntax and a reg ex for "smart" emphasis (ignoring underscores within a word). -* Steward Midwinter wrote command-line parser and cleaned up comments. -* Many other people helped by reporting bugs. - -<a name="License"></a> -<h3 class="title">License</h3> - -The code is dual-licensed under -[GPL](http://www.gnu.org/copyleft/gpl.html) and [BSD -License](http://www.opensource.org/licenses/bsd-license.php). Other -licensing arrangements can be discussed. - -<a name="Contact"></a> -<h3 class="title">Contact Info</h3> - -Email qaramazov [at] gmail.com if you have any questions or spot any -bugs. (Feel free to write in English, Russian, Portuguese or -Spanish.) - -Or subscribe to [python-markdown-discuss](http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss). - - -<a name="Change"></a> -<h3 class="title">Recent Changes</h3> - -Oct 11, 2006: Releasing v. 1.6 with a whole bunch of changes (since -May 15), including: - -- Fixed a bug that caused some text to be lost after comments. -- Added exception for PHP tags when handling html blocks. -- Incorporated Sergej Chodarev's patch to fix a problem with ampersand - normalization and html blocks. -- Switched to using optparse. Added proper support for unicode. -- Fixed the <!--@address.com> problem (Tracker #1501354). -- Stopped catching unquoted titles in reference links. Stopped - creating blank headers. - -May 15, 2006: A bug with lists, recursion on block-level elements, -run-in headers, spaces before headers, unicode input (thanks to Aaron -Swartz). Sourceforge tracker #s: 1489313, 1489312, 1489311, 1488370, -1485178, 1485176. (v. 1.5) - -Mar. 24, 2006: Switched to a not-so-recursive algorithm with -_handleInline. (v. 1.4) - -For a full list of changes see CHANGE_LOG.txt in the current version -of markdown. - -<?php include("markdown-footer.php"); ?> diff --git a/sidebar.txt b/sidebar.txt deleted file mode 100644 index 6ac3253..0000000 --- a/sidebar.txt +++ /dev/null @@ -1,37 +0,0 @@ -SourceForge</p> - -* [Download](http://sourceforge.net/project/showfiles.php?group_id=153041) -* [Report a Bug](http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198) -* [Mailing List](http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss) -* [Subversion](http://sourceforge.net/svn/?group_id=153041) - -This Page - -* [Summary](index.php#Summary) -* [Installation](index.php#Installation) -* [Command Line Usage](index.php#Commandline) -* [Using the Module](index.php#Module) -* [Extending](index.php#Extending) -* [Using Markdown with Django](index.php#Django) -* [License](index.php#License) -* [Contact Info](index.php#Contact) -* [Credits](index.php#Credits) -* [Change Log](index.php#Change) -* [RSS/XML](news.rss) - -Extensions - -* [Table of Contents](extensions/markdown_with_toc.py) -* [WikiLinks](http://achinghead.com/archives/67/adding-wikilinks-to-markdown-in-python/) -* [Python Code Highlighting](http://www.lethalman.net/2006/03/11/markdown-extension-to-highlight-python-code/) -* [Simple Tables](http://k7a.org/tables_python_markdown/) - -Integration - -* [with MoinMoin](http://wiki.vja2.net/MyMoinPlugins) -* [with Django](http://achinghead.com/archives/70/django-blog-and-markdown/) (also [here](http://www.postneo.com/2005/08/10/django-markup-template-tags)) -* - -Related Projects - -* [mkdn2latex](http://www.thefactz.org/archives/144) - convert Markdown to Latex
\ No newline at end of file |