Export Extensions

Export Extensions were introduced in ReText 3.0 and allow you to add your own export functions to ReText.

These extensions work without needing to save the original file — ReText will write a temporary file in original markup or in HTML, depending on what arguments you specify in the command.

The specification

Basics

An export extension is a desktop-file located in RETEXT_PREFIX/share/retext/export-extensions, currently supported prefixes are /usr and ~/.local. Export extension file should have a .desktop extension.

It is possible to write extensions that are compatible with the Desktop Entry Specification.

Export extensions take Markdown, reStructuredText or HTML files as input file.

Structure of the file

Here's a basic file structure:

[Desktop Entry]
# First line is optional
Key1=Value1
Key2=Value2
...

Supported keys

Currently supported keys are Name, Name[locale], Icon, Exec, MimeType, FileFilter and DefaultExtension.

Keys Exec, FileFilter and DefaultExtension may have a X-ReText- vendor prefix.

Key	Description
Name, Name[locale]	Displayed name of the extension, with possible localizations
Icon	Name of the icon in the icon theme
Exec	Absolute path to command being executed, with some arguments (see section below)
MimeType	When set, the extension will be enabled with a certain file type. Use text/x-{retext-}markdown, text/x-{retext-}rst or text/html here.
FileFilter	Used in save dialog, should be in form of QFileDialog file filter (example: Filter 1 (*.ext11 *.ext12);;Filter 2 (*.ext2))
DefaultExtension	Default extension that dialog will append to the file (example: .ext)

Command arguments

These arguments, if given in Exec key string, ReText will replace:

Argument	Replaced with
%if	Input file name (Markdown or reStructuredText)
%html	Input HTML file name
%of	Output file name (will trigger a dialog to allow user select one)

Example of extension

This extension will use pandoc to export a Markdown file to RTF

[Desktop Entry]
Name=Export to RTF
Name[ru]=Экспорт в RTF
Exec=/usr/bin/pandoc -f markdown -t rtf --standalone -o %of %if
X-ReText-FileFilter=RTF Files (*.rtf)
X-ReText-DefaultExtension=.rtf