commit 06dfb8a1af907804d1b012c57e6b8b9de0e478fe
parent b3dfbf18cbe84c2dc8a49eac26549a4795341ab3
Author: lash <dev@holbrook.no>
Date: Mon, 8 Jul 2024 02:16:58 +0100
Local markdown viewer post
Diffstat:
3 files changed, 291 insertions(+), 32 deletions(-)
diff --git a/content.proposed/20240517_localmd.rst b/content.proposed/20240517_localmd.rst
@@ -1,30 +0,0 @@
-Local documentation viewers
-###########################
-
-:date: 2024-05-17 13:35
-:category: Hygiene
-:author: Louis Holbrook
-:tags: bash,markdown,pandoc,vimb,buku
-:slug: local-doc-view
-:summary: Bash script to render and spawn a viewer for markdown files
-:lang: en
-:status: draft
-
-
-Have you noticed that when you start a modern gorilla browser, it will always call to the network.
-
-Be it a chromium or a mozilla, no matter how you tell it no home page, no restoration, and any other available tweak of settings, it will always make at least that one call.
-
-At first glace, this may be a silly thing to get hung up on. Why would you even use a browser if it wasn't to go online, righT?
-
-
-Pin down Markdown
-=================
-
-I consider Markdown to be the fast-food of documents.
-
-That doesn't change the fact that it's everywhere. So much everywhere, in fact, that it's kind of puzzling there is not a dedicated tool around to view it.
-
-There is no shortage of applications that _can_ render markdown. Among the alternatives are free code editors like atom or sublime, the browser plugin Markdown Viewer and even a dedicated markdown editor Mark Test.
-
-But these are not simple viewers. What is the equivalent of xv or feh for Markdown? Honestly, I couldn't find one.
diff --git a/content/20240517_localmd.rst b/content/20240517_localmd.rst
@@ -0,0 +1,284 @@
+Support Your Local Viewer
+#########################
+
+:date: 2024-07-07 21:03:40
+:category: Offlining
+:author: Louis Holbrook
+:tags: bash,markdown,pandoc,vimb,w3m,lynx,xdg
+:slug: local-markdown
+:summary: Bash script to render and spawn a viewer for markdown files
+:lang: en
+:status: published
+
+
+Markdown is the fast-food of document formats.
+
+That doesn't change the fact that it's everywhere.
+
+So much everywhere, in fact, that it's kind of puzzling there is not a dedicated tool around to view it.
+
+
+Pinning down markdown
+=====================
+
+There is no shortage of applications that *can* render markdown. Among the alternatives are free code editors like Atom_ or Geany_, the browser plugin `Markdown Viewer`_ and even a dedicated markdown editor like Marktext_.
+
+And of course, there exist SaaS offerings such as hackmd_. But seeing as those are not alternatives for offline use, we don't concern ourselves with those here.
+
+But what is the equivalent of sxiv_ or feh_ for Markdown?
+
+Honestly, I couldn't find any such thing. If there is, I'd `love to know`_.
+
+Fortunately, there is a perfectly reasonable workaround.
+
+
+Step by step
+============
+
+After all, it is in the spirit of \*nixes to use a choice of tools who *does one thing and does it well*.
+
+So, no matter how bizarre it feels, it may make sense that a lurid format like *Markdown* should be treated in a separate step to produce a more well-established - and less ambiguous - format.
+
+I asked a related question on Stackexchange_ long ago, and there the ``pandoc`` tool came up as a solution.
+
+And it turns out it works beautifully in this case aswell.
+
+Consider the following script:
+
+.. code-block:: bash
+
+ t=$(mktemp --suffix=.html)
+ 2>&1 echo $t
+ pandoc -f gfm -t html -M document-css=false --standalone $1 > $t 2> /dev/null
+ w3m $t
+
+
+Quite simply, we generate a standalone html file in ``tmpfs``, which in turn is read and renderered by a web browser.
+
+
+Browsing browsers
+=================
+
+No appreciation for w3m_, eh? Instead want that fuzzy feel of comforting colors, smooth scroll and fancy fonts?
+
+I can understand. I used to suffer that affliction, too.
+
+But nonetheless; it's an important point. For example, what if I wanted to use lynx_ or vimb_ instead? Choosing the browser to view with should definitely be the caller's call.
+
+Is there a canonical way of doing that in Linux.
+
+Kind of.
+
+Let's review a couple of the options.
+
+
+The environmental solution
+--------------------------
+
+Some applications honor the ``$BROWSER`` environment variable. So let's cover for that:
+
+.. code-block:: bash
+
+ browser=${BROWSER:-w3m}
+ t=$(mktemp --suffix=.html)
+ pandoc -f gfm -t html -M document-css=false --standalone $1 > $t 2> /dev/null
+ $browser $t
+
+Now, viewing the markdown file ``README.md`` with ``lynx`` is as easy as:
+
+.. code-block:: console
+
+ $ BROWSER=$(which lynx) bash wmd.sh README.md
+
+
+The cross solution
+------------------
+
+So, have you heard about the Cross Desktop Group? [1]_ These are the guys you should be sending a thought of gratitude every time you intuitively look in your ``~/.config`` or ``~/.local`` folder for application data. And if you're a **HUIf** [2]_ coder, chances are you have seen the string ``xdg`` in some function call somewhere.
+
+These days they go by the name `Free Desktop Group`_, and among other things they have negotiated something particularly useful to us in this particular case.
+
+To launch programs in a desktop environment in Linux, a `Desktop Entry Specification`_ file format [3]_ has been defined - appropriately suffixed ``.desktop``.
+
+Take a look at a random ``*.desktop`` file in ``/usr/share/applications`` (your most likely default ``$XDG_DATA_DIRS`` location, where xdg searches for desktop files). Every one will contain an top-level ``Exec=`` entry.
+
+For example, my ``feh.desktop`` entry has ``Exec=feh --start-at %u`` which means find ``feh`` in ``$PATH`` and execute it with the ``--start-at`` switch and one single *url* as argument:
+
+.. code-block:: ini
+
+ [Desktop Entry]
+ Name=Feh
+ Name[en_US]=feh
+ GenericName=Image viewer
+ GenericName[en_US]=Image viewer
+ Comment=Image viewer and cataloguer
+ Exec=feh --start-at %u
+ Terminal=false
+ Type=Application
+ Icon=feh
+ Categories=Graphics;2DGraphics;Viewer;
+ MimeType=image/bmp;image/gif;image/jpeg;image/jpg;image/pjpeg;image/png;image/tiff;image/webp;image/x-bmp;image/x-pcx;image/x-png;image/x-portable-anymap;image/x-portable-bitmap;image/x-portable-graymap;image/x-portable-pixmap;image/x-tga;image/x-xbitmap;image/heic;
+ NoDisplay=true
+
+Covering this case in our script:
+
+.. code-block:: bash
+
+ fallbackbrowsercmd=w3m
+ browsercmd=
+ # if browser env exists, then
+ # try handle it as a desktop entry
+ if [ ! -z "$BROWSER" ]; then
+ # find the xdg paths
+ XDG_DATA_DIRS=${XDG_DATA_DIRS:-/usr/share}
+ if [ ! -z "$XDG_DATA_HOME" ]; then
+ XDG_DATA_DIRS=$XDG_DATA_HOME:$XDG_DATA_DIRS
+ fi
+ # split on ":" and try dirs one by one
+ # use first matching browser desktop entry
+ _ifs=$IFS
+ IFS=:
+ dirs=("$XDG_DATA_DIRS")
+ for d in $dirs; do
+ s=$BROWSER.desktop
+ a=$d/applications/$BROWSER.desktop
+ if [ -f "$a" ]; then
+ browsercmd="gtk-launch $s"
+ fi
+ done
+ IFS=
+ fi
+ # if no browser set or could not be found in xdg,
+ # then try the browser env var as command, or
+ # ultimately the static fallback
+ if [ -z "$browsercmd" ]; then
+ browsercmd=${BROWSER:-$fallbackbrowsercmd}
+ fi
+ t=$(mktemp --suffix=.html)
+ pandoc -f gfm -t html -M document-css=false --standalone $1 > $t 2> /dev/null
+ $browsercmd $t
+
+
+The default solution
+--------------------
+
+Yes, there is such a thing as "default web browser" in ``XDG``, too.
+
+Have a look at ``xdg-settings --list``. On my system, it shows a rather modest output:
+
+.. code-block:: console
+
+ $ xdg-settings --list
+ Known properties:
+ default-url-scheme-handler Default handler for URL scheme
+ default-web-browser Default web browser
+
+And the default web browser is:
+
+.. code-block:: console
+
+ $ xdg-settings get default-web-browser
+ brave-browser.desktop
+
+Yeah, yeah, yeah. Busted. I use graphical browsers, too.
+
+Now let's add this to the mix, then.
+
+.. code-block:: bash
+
+ fallbackbrowsercmd=w3m
+ browsercmd=
+ # if browser env var not set, set it with default browser
+ if [ -z "$BROWSER" ]; then
+ BROWSER=$(xdg-settings get default-web-browser)
+ BROWSER=${BROWSER%%.*}
+ fi
+ if [ ! -z "$BROWSER" ]; then
+ XDG_DATA_DIRS=${XDG_DATA_DIRS:-/usr/share}
+ if [ ! -z "$XDG_DATA_HOME" ]; then
+ XDG_DATA_DIRS=$XDG_DATA_HOME:$XDG_DATA_DIRS
+ fi
+ _ifs=$IFS
+ IFS=:
+ dirs=("$XDG_DATA_DIRS")
+ for d in $dirs; do
+ s=$BROWSER.desktop
+ a=$d/applications/$BROWSER.desktop
+ if [ -f "$a" ]; then
+ browsercmd="gtk-launch $s"
+ fi
+ done
+ IFS=
+ fi
+ if [ -z "$browsercmd" ]; then
+ browsercmd=${BROWSER:-$fallbackbrowsercmd}
+ fi
+ t=$(mktemp --suffix=.html)
+ pandoc -f gfm -t html -M document-css=false --standalone $1 > $t 2> /dev/null
+ $browsercmd $t
+
+
+Naming the executioner
+======================
+
+So now we have a markdown viewer. And it can be as lean or as heavy as you want it to be. It's all to the browser you choose.
+
+To make it accessible, map the script as a command alias in your ``.profile`` or ``.bashrc`` and you have the viewer at your fingertips.
+
+I call mine ``wmd``:
+
+
+.. code-block:: bash
+
+ alias wmd="bash $HOME/scripts/markdown.sh"
+
+And voilá:
+
+.. code-block:: console
+
+ $ export BROWSER=lynx
+ $ wmd README.md
+
+..
+
+ .. [1] Or X Desktop Group, as they were originally called.
+
+
+..
+
+ .. [2] Human User Interface. Don't bother looking - I made it up. As the cause of AI, robots and machines inevitably will become appropriated by the woke intersectionality complex, the terminology is probably going to need such distictions.
+
+
+..
+
+ .. [3] Actually the format is ini_. The standard is rather in the file naming, really.
+
+.. _Free Desktop Group: https://www.freedesktop.org/
+
+.. _Desktop Entry Specification: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html
+
+.. _Atom: https://atom-editor.cc/
+
+.. _Geany: https://plugins.geany.org/markdown.html
+
+.. _Markdown Viewer: https://chromewebstore.google.com/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk
+
+.. _Marktext: https://github.com/marktext/marktext
+
+.. _Stackexchange: https://tex.stackexchange.com/questions/341899/latex-to-markdown-converter
+
+.. _w3m: https://w3m.sourceforge.net
+
+.. _lynx: https://lynx.browser.org
+
+.. _vimb: https://fanglingsu.github.io/vimb
+
+.. _sxiv: https://github.com/muennich/sxiv
+
+.. _feh: https://feh.finalrewind.org
+
+.. _hackmd: https://hackmd.io
+
+.. _love to know: https://holbrook.no/msg
+
+.. _ini: https://en.wikipedia.org/wiki/INI_file
diff --git a/lash/static/css/style.css b/lash/static/css/style.css
@@ -40,13 +40,18 @@ header div {
# list-style-type: none;
#}
+h3 {
+ color: #840020;
+ font-size: 1.5em;
+}
+
h2 {
color: #840020;
- font-size: 1.7em;
+ font-size: 2.0em;
}
h1 {
- font-size: 2.2em;
+ font-size: 3.0em;
text-transform: uppercase;
}
