formiko 2.0.0

Custom directives

Formiko registers additional directives that are available in both reStructuredText and MarkDown (via M2R2) documents.

.. file-tree:: <path>

Renders a directory tree rooted at path (relative to the source file) as a bullet list.

Options:

:depth: <n>

Maximum display depth. Default is 2.

:include: <pattern>

Show only files matching the glob pattern (e.g. *.md). Directories with no matching files are hidden automatically.

:exclude: <pattern>

Hide files matching the glob pattern. Applied after :include:.

:links:

Turn file names into hyperlinks pointing to the files, with paths relative to the source document.

Example:

.. file-tree:: docs
   :depth: 3
   :include: *.rst
   :links:

.. mdinclude:: <file>

Includes a Markdown file and converts it to reStructuredText inline. Requires m2r2. The directive is intended for Markdown files, but works in RST documents as well.

Options:

:start-line: <n>

Start reading the file from line n.

:end-line: <n>

Stop reading the file at line n.

Example:

.. mdinclude:: CONTRIBUTING.md
   :start-line: 3

Vim support

Formiko has Neovim editor support aka formiko-vim command. This runs Neovim editor in Vte.Terminal.

recommended:

• m2r2 - converting MarkDown to reStructuredText

• Pygments - syntax color in html output code blocks

• docutils-tinyhtmlwriter - Tiny HTML Writer

formiko-vim:

• vte - Terminal emulator widget

• neovim - heavily refactored vim fork

• pynvim - Python3 library for scripting Neovim processes

development:

• pygobject-stubs

Flatpak

Formiko exists in the Flathub repository as cz.zeropage.Formiko. If you are new with Flatpak, see setup guide.

# add Flathub repository as root
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# install Formiko as user
flatpak install flathub cz.zeropage.Formiko

# run Formiko
flatpak run cz.zeropage.Formiko

Debian based

Debian-based distributions sometimes use versions in package names. Here is an example for the Debian Forky version. If you use a different version, your gtksource or webkit2 may have a different version name.

# python3, gtk4 etc are in dependencies
apt install python3-pip python3-gi python3-docutils python3-jsonpath-ng \
            python3-pygments gir1.2-gtksource-5 gir1.2-webkit-6.0 \
            gir1.2-spelling-1 gir1.2-adw

pip3 install formiko --break-system-packages

# languages
apt install hunspell-en-us  # or other language you want

# neovim
apt install gir1.2-vte-3.91 neovim python3-pynvim

NetBSD

Broken at this moment - the WebKit with GTK4 and the libspelling packages are not available at this moment

Installation process can be different for each BSD releases. It’s about which Python release is default. By this, you can change py313 to your right version.

NetBSD use pkgsrc, so some binaries are stored in /usr/pkg/bin directory. Formiko call neovim directly. If you want to use neovim version with pkgsrc, you must fix VIM_PATH variable in formiko/vim.py file.

# python3.13 is in dependencies, as is gtk4
pkgin install py313-pip py313-gobject3 py313-docutils gtksourceview5 \
              libadwaita librsvg webkit-gtk
pip3.6 install jsonpath-ng formiko

# optionally
pkgin install neovim pynvim
pip3.6 install m2r2 docutils-tinyhtmlwriter

FreeBSD

Installation process can be different for each BSD releases. It’s about which Python release is default. By this, you can change py311 to your right version.

On FreeBSD you must install all these packages:

pkg install py311-pygobject py311-docutils py311-pygments py311-pip \
    gtksourceview5 webkit2-gtk_60 libspelling py311-jsonpath-ng \
    libadwaita

pip-3.11 install formiko

Optionally

# MarkDown, and tiny writer support
pip-3.11 install m2r2 docutils-tinyhtmlwriter

# languages
pkg install en-hunspell  # or other language you want

# neovim
pkg install vte3 neovim py311-pynvim py311-typing-extensions