reformed

Document format conversion service based on Pandoc.

Usage

The API specification for the Reformed server is as follows:

GET /api/v1/formats: Lists available input and output formats for documents

Response

{
  "input": {
    "commonmark": {
      "mime": "text/markdown",
      "ext": "md",
      "detail": "CommonMark Markdown"
    },
    "docx": {
      "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "ext": "docx",
      "detail": "Word docx"
    },
    // ...
  },
  "output": {
    "commonmark": {
      "mime": "text/markdown",
      "ext": "md",
      "detail": "CommonMark Markdown"
    },
    "docx": {
      "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "ext": "docx",
      "detail": "Word docx"
    },
    // ...
    "latex": {
      "mime": "text/x-tex",
      "ext": "tex",
      "detail": "LaTeX"
    },
    // ...
  }
}

POST /api/v1/from/[input format]/to/[output format]: Converts a document from one format to another

Request

The request should be made with the multipart/form-data encoding.

Parameters

The request parameters are as follows:

File document

Document to convert. For example, to convert a docx file to a pdf file, the following cURL command will work:

curl -X POST -F '[email protected]' http://localhost:8000/api/v1/from/docx/to/pdf > test.pdf

Boolean bundle

Whether to bundle the created document and any media (extracted pictures from e.g. a .docx file) together in a .zip archive.

If the form value for this option is anything except a blank string, it will be treated as True.

If no media is generated and this option is set, this will return the reformatted document in a .zip archive by itself.

If media is generated and this option is not set, any extracted media will be discarded and just the document will be returned.

Boolean Pandoc flags

This endpoint supports the following Pandoc standalone flags: ascii, gladtex, html-q-tags, incremental, listings, mathml, no-highlight, number-sections, preserve-tabs, reference-links, section-divs, standalone, strip-comments, toc.

If the form value for a given flag is anything except a blank string, it will be added to the Pandoc call.

See the Pandoc manual for more information on these flags' effects.

Pandoc flags with choices

This endpoint supports the following Pandoc flags which have specific choices: eol, markdown-headings, reference-location, top-level-division, track-changes, wrap.

If the form value for a given flag is valid, it will be added to the Pandoc call.

See the Pandoc manual for more information on these flags' effects.

Integer columns (Pandoc option)

If specified and a valid integer, this will add the --columns=XX option to the Pandoc call. The value is bounded to 1 <= columns <= 300 by Reformed.

See the Pandoc manual's description for more.

Integer dpi (Pandoc option)

If specified and a valid integer, this will add the --dpi=XX option to the Pandoc call. The value is bounded to 36 <= dpi <= 600 by Reformed.

See the Pandoc manual's description for more.

Integer toc-depth (Pandoc option)

If specified and a valid integer, this will add the --toc-depth=XX option to the Pandoc call. The value is bounded to 1 <= toc-depth <= 6 by Reformed.

See the Pandoc manual's description for more.

Response

A binary stream with the MIME type specified in the list of formats. Content-Disposition is forced to be an attachment to prevent files from rendering in the browser.

If an error is encountered, this will instead be a JSON response with an error key specifying what went wrong.

Configuration

A few configuration environment variables are available for the Reformed server, listed here with their default values:

# Maximum buffer size for requests, in bytes - mostly useful for controlling file uploads
# Defaults to 25 MiB
REFORMED_MAX_BUFFER_SIZE=26214400

# Port to accept requests on
REFORMED_PORT=8000

# Number of worker processes to start
REFORMED_WORKERS=2

Deploying

Main-branch and tagged releases are both automatically published as Docker images to the GitHub Container Registry. These images can be run in the standard fashion as a daemon, and expose a Tornado HTTP server on port 8000.

See the package listing for more information on pulling the image.

Developing and Testing

The development requirements are specified in requirements.dev.txt.

To test with coverage, use the following command:

coverage run -m unittest -v

To run the linter, use the following command:

flake8 reformed