GitHub | Issues | Changelog

showmark is a Flask application for viewing rendered markup documents in a browser. It was developed solely for my personal use and is not intended to be consumed generally; use it at your own risk. In particular, it allows viewing files located on the system where the Flask application runs; it is the administrator's responsibility to secure this access appropriately.

showmark supports the following markup formats, recognized by file extension (case insensitive):

• reStructuredText (.rst) — rendered using docutils
• Markdown (superset of CommonMark) (.md) — rendered using myst-parser
  • The following parser extensions are enabled:
    • deflist
    • dollarmath
    • linkify
    • replacements
    • smartquotes

Installation

showmark requires Python 3.10 or higher. Just use pip for Python 3 (You have pip, right?) to install it:

python3 -m pip install git+https://github.com/jwodder/showmark.git

Web Application

The showmark web application consists of a single page. At the top of this page is a form with an input box, a "View" button, and a "List All" button. The user is expected to enter a file path (bare basename, relative path, or absolute path) in the input box, after which pressing the buttons has the following effects:

• "View" — If the path supplied in the input box is a basename or relative path, then showmark performs a breadth-first traversal of each directory specified in the SHOWMARK_SEARCH_PATH configuration option (see below) in turn, looking for a directory to which appending the input path results in an extant file path; the first such file found has its contents rendered & displayed.

  If the input path is absolute, then if it also begins with one of the directories in SHOWMARK_SEARCH_PATH and points to an extant file, that file has its contents rendered & displayed.

  Any filesystem errors that occur while traversing or inspecting paths are ignored.

• "List All" — All files matching the input path (using the same rules as for "View") are found and displayed as a collection of hyperlinks; clicking on a link sends the user to a page displaying that file's rendered contents.

Configuration

showmark supports the following configuration options. These can be set by defining them in a Python source file that is then pointed to by the environment variable SHOWMARK_SETTINGS and/or by setting each option as an environment variable FLASK_{name}.

SHOWMARK_SEARCH_PATH

An os.pathsep-separated list of directories (located on the system on which the application runs) to search for files to render. Defaults to the user's home directory.

SHOWMARK_WRITER_NAME

The name of the docutils writer to use for rendering markup. Defaults to html5.

Development Server

showmark can be served in a local development server on port 8080 by running hatch run local:run. This sets SHOWMARK_SEARCH_PATH to $HOME/work.

Installation on macOS

showmark was successfully installed on a macOS Sonoma system as follows, resulting in it being served by the built-in Apache server (already enabled) at <http://localhost/showmark>:

• Install uwsgi via Homebrew: brew install uwsgi
• Create a virtual environment at /Library/WebServer/Documents/venvs/showmark and install the showmark package into it

• Create the file $HOMEBREW_PREFIX/etc/uwsgi/apps-enabled/showmark.ini with the following contents:

  [uwsgi]
  plugin = python3
  socket = /tmp/org.varonathe.showmark.sock
  # Replace the below with your own search path:
  env = FLASK_SHOWMARK_SEARCH_PATH=/Users/jwodder/work
  module = showmark.app:create_app()
  virtualenv = /Library/WebServer/Documents/venvs/showmark
  manage-script-name = true
  need-app = true
  master = true
  processes = 2
  threads = 5
  harakiri = 60
  vacuum = true

• Enable uwsgi as a system-level daemon: sudo brew services start uwsgi
  • Using sudo is necessary so that the service will be system-level rather than a user agent, which is needed so that the service will run as the _www user and thus be able to read & write to the socket without messing with permissions.
• Configure Apache by editing /etc/apache2/httpd.conf as follows:

  • Uncomment the following lines:

    LoadModule proxy_module libexec/apache2/mod_proxy.so
    LoadModule proxy_uwsgi_module libexec/apache2/mod_proxy_uwsgi.so

  • Add the following line:

    ProxyPass /showmark unix:/tmp/org.varonathe.showmark.sock|uwsgi://showmark/

• Restart Apache: sudo apachectl restart

Updating

After installing showmark as shown above, the package can be updated to a newer version by running:

/Library/WebServer/Documents/venvs/showmark/bin/pip install --upgrade \
    git+https://github.com/jwodder/showmark.git

sudo brew services restart uwsgi