TIP MarkdownPlugin is not installed on Foswiki.org.


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:

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.


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


or by using the %MARKDOWN makro:


or by reading a file attachment:

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


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.


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.


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


Italics: *asterisks* or _underscores_

Bold:  **asterisks** or __underscores__.

Bold Italics: **asterisks and _underscores_**.

Strikethrough: ~~Scratch this.~~


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

[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


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

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

![alt text][logo]

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


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

var s = "JavaScript syntax highlighting";

s = "Python syntax highlighting"
print s

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


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 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.



Change History

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
Topic revision: r4 - 03 May 2022, MichaelDaum
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy