Using pandoc

From ActinoBase
Revision as of 14:08, 25 October 2019 by LeightonP (talk | contribs) (add page describing use of pandoc to convert Word documents to MediaWiki format)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Introduction

MediaWiki pages are edited using a specific syntax, which can take a while to get the hang of. It is, however, possible to write your pages in a word processor, such as Microsoft Word, and use a tool like pandoc to convert the article to MediaWiki format for you. This can be much less painful (and help in understanding how MediaWiki formatting works).

This page aims to guide you through the process of obtaining and using pandoc to convert a page written in Microsoft Word to MediaWiki format, so it can be copy/pasted directly into the wiki.

Installing Pandoc

Pandoc works on Microsoft Windows, macOS, and Linux. Installer packages for pandoc can be found at the releases page:

To install pandoc, download the installer for your operating system, and double-click on it to run. Follow the instructions on-screen.

Using Pandoc

Pandoc is a tool designed to convert documents from one format to another. This tool is used by typing at the command-line/terminal, and the usual command structure is:

pandoc -f <INPUT_FORMAT> -t <OUTPUT_FORMAT> -o <OUTPUT_FILENAME> <INPUT_FILENAME>

Pandoc can convert between a wide range of formats, and as an example, we'll use a small Microsoft Word document with some header and list structures as input.

Example

  • Input Word file

To convert this file to MediaWiki format, use the following command from the same directory as the Word file:

pandoc -f docx -t mediawiki -o example.txt example.docx

The output from the conversion (written out into example.txt looks like this:

= This is a top-level header =

And this is some text that goes under our top-level heading.

== Here’s a subheading ==

There are some things relevant to the subheading. Let’s list them

# Item 1
# Item 2
# Item 4 (item 3 is unavailable)

We could put these in a table:

{|
! Thing
! Number
! Available?
|-
| Item
| 1
| Yes
|-
| Item
| 2
| Yes
|-
| Item
| 3
| No
|}

and when copied and pasted into the wiki, renders like this:

This is a top-level header

And this is some text that goes under our top-level heading.

Here’s a subheading

There are some things relevant to the subheading. Let’s list them

  1. Item 1
  2. Item 2
  3. Item 4 (item 3 is unavailable)

We could put these in a table:

Thing Number Available?
Item 1 Yes
Item 2 Yes
Item 3 No