title	tags
README	markdown, browser, render, UserJS, greasemonkey, tampermonkey

markdown-render

markdown-render is a user javascript, running in-browser, which automatically renders raw local markdown files (eg, "file://PATH/TO/file.mkd") into HTML.

<style> kbd { /* modified from https://auth0.github.io/kbd/ */ font-family: Consolas, "Lucida Console", monospace; display: inline-block; border-radius: 3px; padding: 0px 4px; box-shadow: 1px 1px 1px #777; margin: 2px; font-size: 0.9em; line-height: 1.1; vertical-align: text-bottom; background: #eee; font-weight: 500; color: #555; cursor: pointer; font-variant: small-caps; font-weight: 600; /* This two work */ /* letter-spacing: 0.5px; */ letter-spacing: 1px; /* Prevent selection */ -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; } </style>

Setup

1. Setup the browser userscript manager

   • install the TamperMonkey extension from TamperMonkey
     • for Chrome, it may, alternatively, be installed via the Chrome web store
     • for Firefox, it may, alternatively, be installed via Firefox Add-ons

2. Enable TamperMonkey scripting of file URLs

   • Chrome
     1. open chrome://extensions
     2. for the TamperMonkey extension, ENABLE the Allow access to file URLs option
     • for more detailed explanation, see the TamperMonkey FAQ or video ^@
   • Firefox ... not needed

3. Install the markdown-render userscript

   1. open https://github.com/rivy/js-user.markdown-render/raw/master/dist/markdown-render.user.js
   2. CLICK Install in the TamperMonkey installation dialog

Optional ∾ For best results when reading files with leading HTML/XML-like elements, enable access to all local files for TamperMonkey scripts.

1. Open the TamperMonkey Dashboard by clicking on Dashboard in the TamperMonkey drop-down list from the browser toolbar
2. Select the Settings tab
3. In the Security section, for Allow scripts to access local files:, select All local files, and click the Save button

This allows markdown-render to re-read any local file which may have been misread (and mangled) as HTML/XML instead of 'text/plain'. Notably, this allows any user script to access any local file, so use with care.

Known Limitations

Incorrect interpretation of files with initial HTML tags

• TLDR; when possible, avoid initial HTML/XML-like elements within the markdown file.

While most markdown files are correctly interpreted, those with leading HTML/XML-like elements are problematic. Both Chrome and Firefox will interpret and parse a file as HTML if it contains any initial HTML content, even if the file extension is not ".htm", ".html", or ".xml". This interpretation and parsing of the file happens during loading and results in an irretrievable garbling of file contents and a subsequent inability to correctly render the file.

Both Chrome and Firefox, through various techniques and some extra, manually enabled, user permissions, can be coerced into re-reading the file as text. But the techniques are workarounds and can't expected to work for all future browser versions.

A "workaround" is to always use initial content without HTML elements, such as a DOCTYPE declaration (eg, <!DOCTYPE markdown> [uppercase 'DOCTYPE' preferred for widest compatibility]). A DOCTYPE declaration works for all browsers and is completely valid markdown. Alternatively, using YAML front matter elements will also prevent the destructive as-HTML interpretation of the file.

As of 2019-08, Firefox now interprets leading XML elements (eg, <!DOCTYPE ...>) as HTML elements, leading to misinterpretation of the file. Chrome still reads the file as pure text.

For Firefox, any non-HTML/XML character sequence will stimulate a "text/plain" interpretation of the file. So, YAML or title text first in the file will work. Notably, for Github's markdown, initial YAML will appear as a table of values at the top of the converted page. Additionally &nbsp;<!--{style="display:none"}--><!DOCTYPE markdown> or 📖<!--{style="display:none"}--><!DOCTYPE markdown> will also work although either add an initial blank line, or line with a character, for parsers which don't implement 'markdown-it-decorate' comment-style attribute application.

<!DOCTYPE markdown> is currently the best option for Chrome; for Firefox ... the kata is a work-in-progress, but the file can be re-read if the content-type is not "text/plain" (or "text/markdown"); possibly testing for "text/html" and re-reading in that case would be best. Firefox makes the most mistakes, but it's less used and can easily re-read the file (in no noticeable with an SSD), using <!DOCTYPE markdown> is likely the best option.

Edge isn't usable

• TLDR; use Chrome or Firefox as default handlers for files with markdown file extensions.

MS Edge won't open and render local files, except for files with specific extensions (eg, ".html"). And there is no current method to enable reading and rendering of new file types / extensions (eg, all the markdown extensions). So, while the script may actually work, it's impossible to test or use at this moment. If a markdown file is opened, it will be pushed to whichever application is setup as the default handler. Luckily, either of the more capable Chrome or Firefox browsers can be set as the default handler for files with the various markdown extensions, which ultimately solves the problem.

Build

• use NodeJS v16 or earlier; NodeJS v17+ causes build errors and won't package the script
• recipe:

npm install ## or `npm clean-install` (to use "package-lock.json" deps)
npm run build