md2fd

Produce a clean, acceptable F-Droid description from existing Markdown.

This is a command-line tool (Linux/Windows/macOS) that converts a Markdown file (eg a project README.md) into a suitable /metadata/**/full_description.txt for submission to F-Droid.

The general approach is progressive enhancement:

• Prioritise clean, readable plain text
• Retain the subset of HTML tags allowed by F-Droid
• Degrade unsupported tags gracefully

The pipeline (roughly)

1. Read a Markdown input file
2. Convert it to HTML
3. Sanitise the HTML according to rules set in a *.yaml config file
4. Output simplified HTML (optionally preview in a browser via the --preview flag)

Motivation

Reduce friction during the F-Droid submission process.

Increase the likelihood of the description remaining fresh and current.

Many projects already maintain a decent README.md. It's natural to want use this content (or some of it) to produce the description for F-Droid's listing pages.

F-Droid does not currently publish a rigid official specification but we can for now work to the following rules:

• There is a list of supported HTML tags
• There is a list of prohibited HTML tags
• Links (including href) may work for now but may not in future
• There is a 4000 character limit
• Line breaks are converted to <br> tags (so we want to keep an eye on whitespace)

These rules seem subject to change so we:

• Use a configuration file so that we can adapt to some changes without recompiling the binaries
• More complex changes will require a rebuild but we structure the app to make this as easy as possible

Installation

It's just a binary. Download whichever version suits your OS and CPU architecture, and put it somewhere on your system that makes sense to you (probably somewhere already on your PATH).

You may need to make it executable eg:

sudo chmod +x md2fd

Linux Dependencies

On Linux if you want to use the --preview option (which opens the output in a browser tab) you'll need xdg-utils installed. Most modern desktop distros will have it already, but if you're on a minimal install you may need to:

sudo apt install xdg-utils

Usage

# Output to console
md2fd --input README.md
# Preview the output in your default browser
md2fd --input README.md --preview
# Create/overwrite a file containing converted text
md2fd --input README.md > metadata/en_US/full_description.txt

In the real world there will probably be stuff in your main README.md that isn't fitting for F-Droid. I tend to work on a copy myself.

Configuration

F-Droid rules may change over time so this tool is configurable and tries to make editing the way a given tag is treated as simple as possible.

The first time md2fd is run it will create a default config file named {CONFIG_DIR}/md2fd/md2fd.yaml.

The location of {CONFIG_DIR} will vary depending on your OS:

• Linux: Uses $XDG_CONFIG_HOME if it exists, otherwise defaults to ~/.config (respects the XDG Base Directory Specification)
• macOS: ~/Library/Application Support
• Windows: %AppData% (usually resolves to C:\Users\<username>\AppData\Roaming)

F-Droid HTML Support Summary

F-Droid app descriptions are primarily text-based, with only a small subset of HTML tags allowed.

There is no official, definitive published list, but community experience and Git repository inspection suggest the following:

At time of writing the All About Descriptions, Graphics, and Screenshots page seems to be the most official statement on what's allowed.

The detailed app description may use HTML tags. Note that not all tags are supported by the renderer.

• These simple layout tags are supported: b, big, blockquote, br, cite, em, i, li, ol, small, strike, strong, sub, sup, tt, u, ul. a with href is currently allowed, but might be removed without notice.
• Certain tags are explicitly prohibited, namely applet, base, body, button, embed, form, head, html, iframe, img, input, link, object, picture, script, source, style, svg and video.
• Note that a line break will automatically be converted to a br tag.
• You may not make use of JavaScript.

Also further down the page there's mention of a 4,000 char limit:

 ├── en-US (en-US is the default locale in F-Droid)
 │ ├── title.txt (app name, max 50 chars)
 │ ├── short-description.txt (short description, max 80 chars, mandatory)
 │ ├── full-description.txt (full app description, max 4000 chars, mandatory)
 │ ├── video-url.txt (URL to a video introducing the app)``