https://github.com/jwodder/showmark
Serve rendered markup documents
https://github.com/jwodder/showmark
file-viewer flask markdown python restructuredtext
Last synced: 5 months ago
JSON representation
Serve rendered markup documents
- Host: GitHub
- URL: https://github.com/jwodder/showmark
- Owner: jwodder
- License: mit
- Created: 2024-04-29T21:17:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-29T23:29:07.000Z (7 months ago)
- Last Synced: 2025-06-16T13:05:33.881Z (6 months ago)
- Topics: file-viewer, flask, markdown, python, restructuredtext
- Language: CSS
- Homepage:
- Size: 73.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
|repostatus| |ci-status| |coverage| |license|
.. |repostatus| image:: https://www.repostatus.org/badges/latest/concept.svg
:target: https://www.repostatus.org/#concept
:alt: Project Status: Concept – Minimal or no implementation has been done
yet, or the repository is only intended to be a limited example,
demo, or proof-of-concept.
.. |ci-status| image:: https://github.com/jwodder/showmark/actions/workflows/test.yml/badge.svg
:target: https://github.com/jwodder/showmark/actions/workflows/test.yml
:alt: CI Status
.. |coverage| image:: https://codecov.io/gh/jwodder/showmark/branch/main/graph/badge.svg
:target: https://codecov.io/gh/jwodder/showmark
.. |license| image:: https://img.shields.io/github/license/jwodder/showmark.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`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``
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _docutils: https://docutils.sourceforge.io
.. _CommonMark: https://commonmark.org
.. _myst-parser: https://myst-parser.readthedocs.io
.. _parser extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
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
:
- 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:
.. code:: ini
[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:
.. code:: shell
/Library/WebServer/Documents/venvs/showmark/bin/pip install --upgrade \
git+https://github.com/jwodder/showmark.git
sudo brew services restart uwsgi