MarkdownPlugin

Markdown support for Foswiki

This plugin lets you write content using Markdown, a very popular markup language nowadays. It does not try to replace Foswiki's own TML markup language which is still the preferable way to format text within Foswiki itself. However, somtimes people are more accustomed to Markdown or do want to import existing content of that type to Foswiki and still be able to render it to HTML and even edit it using Foswiki as a content management system.

Markdown is not converted to TML. Instead, it is converted directly to HTML using one of below 3rd party conversion libraries and tools:

• CPAN:Text::Markdown (perl library)
• CPAN:Text::MultiMarkdown (perl library)
• CPAN:Text::Markdown::Hoedown (perl bindings for C library)
• CPAN:Text::Textile (perl library)
• Pandoc (external tool) … recommended

When using the Pandoc converter a couple of extra formats are available as it is able to read a couple of more formats:

• commonmark
• docbook
• docx
• epub
• haddock
• html
• json
• latex
• markdown
• markdown_github
• markdown_mmd
• markdown_phpextra
• markdown_strict
• mediawiki
• native
• odt
• opml
• org
• rst
• t2t
• textile
• twiki

The actual list of input formats might vary depending on pandoc as installed on the Foswiki server.

Usage

Content can either be written within the topic area itself using:

%STARTMARKDOWN%
...
%STOPMARKDOWN%

or by using the %MARKDOWN makro:

%MARKDOWN{text="..."}%

or by reading a file attachment:

%MARKDOWN{topic="..." attachment="....md"}%

Syntax

The %MARKDOWN{...}% makro may take a couple of parameters.

Parameter	Description	Default
"..." or text="..."	specify a markup string
topic="...="	the topic from where to read a markdown attachment or section	current topic
section="..."	named section to extract markdown
attachment="..."	file name of an attachment haning off from topic
url="..."	url from which to fetch markdown text
rev="..."	version of the topic or attachment to extract markdown from	latest
format="..."	when using the Pandoc converter this option specifies one of the supported input formats that pandoc understands	defined in {PandocFormat} defaulting to "markdown"

Note that section, url and attachment are exclusive.

The %STARTMARKDOWN{...}% … %STOPMARKDOWN% is the sectional (or inline) variant of the %MARKDOWN. Alternatively you may write %BEGINMARKDOWN% … %ENDMARKDOWN as well. The only parameter that makes sense here is the format parameter as markdown content is specified inline directly, i.e. not read from a named section or an attachment of course.

Markdown

Here is a short overview of the basic Markdown primitives. Please see http://daringfireball.net/projects/markdown for a more thorough description of the syntax.

Headings

# H1
## H2
### H3
#### H4
##### H5
###### H6

Emphasis

Italics: *asterisks* or _underscores_

Bold:  **asterisks** or __underscores__.

Bold Italics: **asterisks and _underscores_**.

Strikethrough: ~~Scratch this.~~

Lists

1. First ordered list item
2. Another item
  * Unordered sub-list. 
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
4. And another item.

* Unordered list can use asterisks
- Or minuses
+ Or pluses

Links

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself].

URLs and URLs in angle brackets will automatically get turned into links. 
http://www.example.com or <http://www.example.com> and sometimes 
example.com (but not on Github, for example).

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

Images

Here's our logo (hover to see the title text):

Inline-style: 
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

Reference-style: 
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

Code

Inline `code` has `back-ticks around` it.

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

```python
s = "Python syntax highlighting"
print s
```

```
No language indicated, so no syntax highlighting. 
But let's throw in a <b>tag</b>.
```

Tables

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 2 is      | centered      |   $12 |
| col 3 is      | right-aligned | $1600 |
| zebra stripes | are neat      |    $1 |

There must be at least 3 dashes separating each header cell.
The outer pipes (|) are optional, and you don't need to make the 
raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

Blockquotes

> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. 

Horizontal Rule

Three or more hyphens, asterisks or underscores:

---

***

___

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Contrib::CacheContrib	>=0	Required
Text::Markdown	>=1.0	Optional
Text::Markup	>=0	Optional
Parse::BBCode	>=0	Optional
Text::MultiMarkdown	>=1.0	Optional
Text::Markdown::Hoedown	>=1.0	Optional
Text::Textile	>=2.0	Optional
pandoc	>1.12	Required

Change History

30 Apr 2024	added support for Text::Markup and Parse::BBCode
03 May 2022	improve performance by using Foswiki:Extensions/CacheContrib talking to external markdown renderers
06 Oct 2020	added url param
05 Oct 2020	added {PandocFormat} config parameter; fixed several problems that prevented this plugin from being used in wiki apps; fixed encoding pandoc results
10 Apr 2018	fixed syntax error in Config.spec
06 Apr 2018	initial release