Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rivy/js-user.markdown-render
User script to render local markdown files
https://github.com/rivy/js-user.markdown-render
js-user markdown renderer userscript
Last synced: 28 days ago
JSON representation
User script to render local markdown files
- Host: GitHub
- URL: https://github.com/rivy/js-user.markdown-render
- Owner: rivy
- Created: 2017-04-25T19:56:04.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-11-13T07:26:55.000Z (about 1 year ago)
- Last Synced: 2024-10-14T21:05:30.489Z (2 months ago)
- Topics: js-user, markdown, renderer, userscript
- Language: CSS
- Size: 4.78 MB
- Stars: 0
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.mkd
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
---
## editors ## (emacs/sublime) -*- coding: utf8-nix; tab-width: 4; mode: markdown; indent-tabs-mode: nil; basic-offset: 2; st-word_wrap: 'true' -*- ## (jEdit) :tabSize=4:indentSize=4:mode=markdown: ## (notepad++) vim:tabstop=4:syntax=markdown:expandtab:smarttab:softtabstop=2 ## modeline (see @@)
title: README
tags: 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.
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;
}
## Setup
1. Setup the browser userscript manager
- install the TamperMonkey extension from [TamperMonkey](http://tampermonkey.net/index.php)
- for Chrome, it may, alternatively, be installed via the [Chrome web store](https://chrome.google.com/webstore/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo)
- for Firefox, it may, alternatively, be installed via [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/tampermonkey)
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](http://tampermonkey.net/faq.php#Q204) or [video](http://fastly.tampermonkey.net/images/animated/allow_access_to_file_urls.gif) [`@`](https://archive.is/ZGnZc)
- Firefox ... not needed
3. Install the `markdown-render` userscript
1. open
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, `` [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, ``) 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 ` ` or `📖` 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.
`` 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 `` 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:
```shell
npm install ## or `npm clean-install` (to use "package-lock.json" deps)
npm run build
```