search

Cimbali / markdown-viewer

Markdown (.md) file viewer WebExtension for your browser.
Other
167 stars 28 forks source link
markdown webextension

readme

# markdown-viewer

Markdown (.md file) Viewer extension. Displays markdown documents beautified in your browser.

Markdown is a lightweight markup language which uses plain text to describe formatting information, such as # Heading, 1. numbered lists, **bold**, etc. This add-on identifies markdown documents by the extension in the URL (one of .markdown, .md, .mdown, .mdwn, .mkd, .mkdn). When you navigate to a markdown document, if the content is plain text, not already styled (by GitHub for example), this add-on formats it into HTML (with headings, ordered lists, bold text, etc.) using markup from the document and displays it directly in your browser.

This add-on was initially a XUL/XPCOM addon by @Thiht, rewritten for the WebExtensions API by @KeithLRobertson.

Unicode Characters

So, non-ASCII characters in your document aren't displaying correctly? Special characters like " á " appear as " á "? This is a problem of character encoding, which concerns converting a file (a sequence of octets) into text (a sequence of characters) and back. By the time Firefox activates the Markdown Viewer Web Extension for your document, the file is already converted into text, correctly or incorrectly. If the file begins with a Byte Order Marker (BOM), a pseudo-character which tells how the file is encoded, then Firefox will see it and use that encoding. Otherwise, Firefox may have decoded the file with the wrong encoding. Although UTF-8 is the modern de facto standard encoding, Firefox defaults to using your system's regional encoding, yielding incorrect results.

Some extensions have worked around this by re-loading the file and explicitly decoding it as UTF-8, but it is a pain to do so. Plus, this extension is intended to be a light and simple wrapper around the markdown-to-HTML converter, markdown-it.

When the markdown document is obtained from a web site, the site should return a Content-Type header which specifies the encoding. If it does not and the file lacks a BOM, you're out of luck. Contact the web site owner.

When the markdown is loaded from a local file, there are no HTML headers to lean on. Fortunately, Firefox now has a setting which allows specifying that you want to use UTF-8 for local files without a BOM. Go to about:config, search for intl.charset.fallback.utf8_for_file, and set its value to true. It should look better now.

Viewing Original Markdown

To keep it simple, the extension does not support on and off states. If the document has one of the supported extensions, it should convert. Some web sites however, like raw.githubusercontent.com, return CORS headers, in which case Firefox will not inject this extension's content scripts, so it cannot convert the document. On those pages, the extension will display a button in your address bar, and when clicked, take you to a page that can render the document.

If you're viewing pretty markdown and you want to see the original source text, right-click and select "View Page Source". On the extension rendering page, you can instead open the drop-down menu on the page and click “View Source”. (Make sure you don't have any text selected to see that option.) Of course, you can also (Ctrl-S) save the document to a file and open it in any text editor.

Saving Converted Markdown

If you would like to save the HTML-converted text, it is possible to do so in the desktop versions of Firefox.

Custom Appearance

You don't like how the styled markdown looks? There are currently 2 default styles to choose from (not from this repo − under MIT):

There are also a number of highlight.js styles to choose from. Styles ending in auto will automatically pick the dark and light variant based on the prefers-color-scheme value of your browser.

Using CSS, you can further customize the appearance any way you like it. View Add-ons (about:addons), and click Options for the Markdown Viewer. There is a box to enter your Custom CSS text. (Sorry, there is not currently a "user-friendly" drop-down option.) As the instructions there state, click or tab out of the text box to save your changes. The CSS is not validated, so you may want to create your CSS outside the options page (or lift it from a site that you like), and paste it in. If you have entered some changes that you don't want to keep, refresh the options page to discard changes.

For example to assign a maximum width root element in the styled markdown:

.markdownRoot {
    margin: 0 auto;
    max-width: 888px;
    padding: 45px;
    border: lightgrey thin solid;
}

"Can You Add This Feature?"

This is an open-source project with the most liberal usage and change license there is. Please feel free to modify it to meet your needs, and to contribute your improvement back to the community.

Think only experts can do that? Although Keith is a programmer, he could only just make his way around JavaScript, and was a total beginner with the WebExtension browser plugin API. But Keith needed a markdown viewer, and the plugin API which the existing add-on had used was deprecated and removed, so he adapted that add-on to the new technology.

The feature set is expected to grow, not from a single author, but by the contributions of users like you who need some additional capabilities. Several features have been added by community contributors who needed them, which include:

Many thanks to them and to our future contributors. Pull requests are welcomed.

To Build The Extension

To Test The Extension

Firefox won't install the generated .zip file permanently until it's signed by Mozilla. You can test any changes using the cloned project files.

Before that you’ll need to build katex from source (see above).

Support for local files on Linux and macOS

Firefox may not know how to handle markdown files by default (see #2), and if opening them it may suggest to download them instead, so that you may be unable to either automatically render them or access the address bar (“page action”) button. Until Firefox implements mime-type handling for extensions, there are a number of possible workarounds for this. Here are the 3 options that work the best:

1) Open the page via the extension’s rendering page (since v2):

The best way to do this is to go to ext+view-markdown:file:///path/to/file.md. (Note that you can do this also for online pages.) Firefox then requires us to have you confirm file access, through a file picker or drag-and-drop.

Opening a file this way allows to both:

2) Edit Firefox’s private mime types.

These mime types are stored in a file indicated by helpers.private_mime_types_file, by default it is ~/.mime.types. Create this file if it does not exist, otherwise edit it, and add the following line:

   type=text/plain exts=md,mkd,mkdn,mdwn,mdown,markdown, desc="Markdown document"

Then restart firefox.

Important note: On some systems, e.g. Ubuntu 21.10 or newer, firefox may be installed with a system like snap, which prevents it from reading files from your disk such as ~/.mime.types, see #86.

In that case you need to:

3) On Linux only, a workaround is to define the MIME type of markdown file extensions as text/plain.

Add the following XML to ~/.local/share/mime/packages/text-markdown.xml:

   <?xml version="1.0"?>
   <mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
     <mime-type type="text/plain">
       <glob pattern="*.md"/>
       <glob pattern="*.mkd"/>
       <glob pattern="*.mkdn"/>
       <glob pattern="*.mdwn"/>
       <glob pattern="*.mdown"/>
       <glob pattern="*.markdown"/>
     </mime-type>
   </mime-info>

Then run

   $ update-mime-database ~/.local/share/mime

See this SuperUser question for further reading on the topic.