Export Extensions

Dmitry Shachnev edited this page Dec 20, 2015 · 2 revisions

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 -o %of %if
X-ReText-FileFilter=RTF Files (*.rtf)
X-ReText-DefaultExtension=.rtf
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.