{"id":18085071,"url":"https://github.com/jwodder/showmark","last_synced_at":"2026-04-09T21:04:24.684Z","repository":{"id":237086324,"uuid":"793781341","full_name":"jwodder/showmark","owner":"jwodder","description":"Serve rendered markup documents","archived":false,"fork":false,"pushed_at":"2025-05-29T23:29:07.000Z","size":75,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-16T13:05:33.881Z","etag":null,"topics":["file-viewer","flask","markdown","python","restructuredtext"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwodder.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-29T21:17:18.000Z","updated_at":"2025-05-29T23:29:11.000Z","dependencies_parsed_at":"2024-05-02T03:45:09.650Z","dependency_job_id":"c10bb0e7-b928-4d4e-ab6e-f027e9cde713","html_url":"https://github.com/jwodder/showmark","commit_stats":null,"previous_names":["jwodder/showmark"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jwodder/showmark","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwodder%2Fshowmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwodder%2Fshowmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwodder%2Fshowmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwodder%2Fshowmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwodder","download_url":"https://codeload.github.com/jwodder/showmark/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwodder%2Fshowmark/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266813418,"owners_count":23988544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-viewer","flask","markdown","python","restructuredtext"],"created_at":"2024-10-31T15:09:16.502Z","updated_at":"2026-04-09T21:04:24.672Z","avatar_url":"https://github.com/jwodder.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"|repostatus| |ci-status| |coverage| |license|\n\n.. |repostatus| image:: https://www.repostatus.org/badges/latest/concept.svg\n    :target: https://www.repostatus.org/#concept\n    :alt: Project Status: Concept – Minimal or no implementation has been done\n          yet, or the repository is only intended to be a limited example,\n          demo, or proof-of-concept.\n\n.. |ci-status| image:: https://github.com/jwodder/showmark/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/jwodder/showmark/actions/workflows/test.yml\n    :alt: CI Status\n\n.. |coverage| image:: https://codecov.io/gh/jwodder/showmark/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/jwodder/showmark\n\n.. |license| image:: https://img.shields.io/github/license/jwodder/showmark.svg\n    :target: https://opensource.org/licenses/MIT\n    :alt: MIT License\n\n`GitHub \u003chttps://github.com/jwodder/showmark\u003e`_\n| `Issues \u003chttps://github.com/jwodder/showmark/issues\u003e`_\n| `Changelog \u003chttps://github.com/jwodder/showmark/blob/master/CHANGELOG.md\u003e`_\n\n``showmark`` is a Flask application for viewing rendered markup documents in a\nbrowser.  It was developed solely for my personal use and is not intended to be\nconsumed generally; use it at your own risk.  In particular, it allows viewing\nfiles located on the system where the Flask application runs; it is the\nadministrator's responsibility to secure this access appropriately.\n\n``showmark`` supports the following markup formats, recognized by file\nextension (case insensitive):\n\n- reStructuredText_ (``.rst``) — rendered using docutils_\n\n- Markdown (superset of CommonMark_) (``.md``) — rendered using myst-parser_\n\n  - The following `parser extensions`_ are enabled:\n\n    - ``deflist``\n    - ``dollarmath``\n    - ``linkify``\n    - ``replacements``\n    - ``smartquotes``\n\n.. _reStructuredText: https://docutils.sourceforge.io/rst.html\n.. _docutils: https://docutils.sourceforge.io\n.. _CommonMark: https://commonmark.org\n.. _myst-parser: https://myst-parser.readthedocs.io\n.. _parser extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html\n\n\nInstallation\n============\n``showmark`` requires Python 3.10 or higher.  Just use `pip\n\u003chttps://pip.pypa.io\u003e`_ for Python 3 (You have pip, right?) to install it::\n\n    python3 -m pip install git+https://github.com/jwodder/showmark.git\n\n\nWeb Application\n===============\n\nThe ``showmark`` web application consists of a single page.  At the top of this\npage is a form with an input box, a \"View\" button, and a \"List All\" button.\nThe user is expected to enter a file path (bare basename, relative path, or\nabsolute path) in the input box, after which pressing the buttons has the\nfollowing effects:\n\n- \"View\" — If the path supplied in the input box is a basename or relative\n  path, then ``showmark`` performs a breadth-first traversal of each directory\n  specified in the ``SHOWMARK_SEARCH_PATH`` configuration option (see below) in\n  turn, looking for a directory to which appending the input path results in an\n  extant file path; the first such file found has its contents rendered \u0026\n  displayed.\n\n  If the input path is absolute, then if it also begins with one of the\n  directories in ``SHOWMARK_SEARCH_PATH`` and points to an extant file, that\n  file has its contents rendered \u0026 displayed.\n\n  Any filesystem errors that occur while traversing or inspecting paths are\n  ignored.\n\n- \"List All\" — All files matching the input path (using the same rules as for\n  \"View\") are found and displayed as a collection of hyperlinks; clicking on a\n  link sends the user to a page displaying that file's rendered contents.\n\n\nConfiguration\n=============\n\n``showmark`` supports the following configuration options.  These can be set by\ndefining them in a Python source file that is then pointed to by the\nenvironment variable ``SHOWMARK_SETTINGS`` and/or by setting each option as an\nenvironment variable ``FLASK_{name}``.\n\n``SHOWMARK_EXCLUDE_DIRS``\n    An ``os.pathsep``-separated list of names of directories not to recurse\n    into when searching for files to render.  Defaults to the empty string.\n\n``SHOWMARK_SEARCH_PATH``\n    An ``os.pathsep``-separated list of paths to directories (located on the\n    system on which the application runs) to search for files to render.\n    Defaults to the user's home directory.\n\n``SHOWMARK_WRITER_NAME``\n    The name of the docutils writer to use for rendering markup.  Defaults to\n    ``html5``.\n\n\nDevelopment Server\n==================\n\n``showmark`` can be served in a local development server on port 8080 by\nrunning ``hatch run local:run``.  This sets ``SHOWMARK_SEARCH_PATH`` to\n``$HOME/work``.\n\n\nInstallation on macOS\n=====================\n\n``showmark`` was successfully installed on a macOS Sonoma system as follows,\nresulting in it being served by the built-in Apache server (already enabled) at\n\u003chttp://localhost/showmark\u003e:\n\n- Install `uwsgi \u003chttps://uwsgi-docs.readthedocs.io/en/latest/\u003e`_ via Homebrew:\n  ``brew install uwsgi``\n\n- Create a virtual environment at\n  ``/Library/WebServer/Documents/venvs/showmark`` and install the ``showmark``\n  package into it\n\n- Create the file ``$HOMEBREW_PREFIX/etc/uwsgi/apps-enabled/showmark.ini`` with\n  the following contents:\n\n  .. code:: ini\n\n    [uwsgi]\n    plugin = python3\n    socket = /tmp/org.varonathe.showmark.sock\n    # Replace the below with your own settings:\n    env = FLASK_SHOWMARK_SEARCH_PATH=/Users/jwodder/work\n    env = FLASK_SHOWMARK_EXCLUDE_DIRS=_build:build:clones:forks:target:venv\n    module = showmark.app:create_app()\n    virtualenv = /Library/WebServer/Documents/venvs/showmark\n    manage-script-name = true\n    need-app = true\n    master = true\n    processes = 2\n    threads = 5\n    harakiri = 60\n    vacuum = true\n\n- Enable uwsgi as a system-level daemon: ``sudo brew services start uwsgi``\n\n  - Using ``sudo`` is necessary so that the service will be system-level rather\n    than a user agent, which is needed so that the service will run as the\n    ``_www`` user and thus be able to read \u0026 write to the socket without\n    messing with permissions.\n\n- Configure Apache by editing ``/etc/apache2/httpd.conf`` as follows:\n\n  - Uncomment the following lines::\n\n        LoadModule proxy_module libexec/apache2/mod_proxy.so\n        LoadModule proxy_uwsgi_module libexec/apache2/mod_proxy_uwsgi.so\n\n  - Add the following line::\n\n        ProxyPass /showmark unix:/tmp/org.varonathe.showmark.sock|uwsgi://showmark/\n\n- Restart Apache: ``sudo apachectl restart``\n\nUpdating\n--------\n\nAfter installing ``showmark`` as shown above, the package can be updated to a\nnewer version by running:\n\n.. code:: shell\n\n    /Library/WebServer/Documents/venvs/showmark/bin/pip install --upgrade \\\n        git+https://github.com/jwodder/showmark.git\n\n    sudo brew services restart uwsgi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwodder%2Fshowmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwodder%2Fshowmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwodder%2Fshowmark/lists"}