Skip to content

Commit 2b229f3

Browse files
KeithLRobertsonKeithLRobertson
committed
Update 1.4.0
- No longer require browser icon action to dynamically acquire permissions - Remove scripts and images related to dynamic permission management - Use URL pattern matching to signal content loading - Remove URL regex matching on every load and dynamic script injection - Reference the project README from the add-on's Options page - Greatly expand the README file with many helpful tips - Now works in Chrome browser
1 parent 96e3d46 commit 2b229f3

File tree

11 files changed

+244
-221
lines changed

11 files changed

+244
-221
lines changed

‎README.md‎

Lines changed: 99 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,105 @@
1-
# markdown-viewer
2-
Markdown (.md) file viewer [WebExtension](https://developer.mozilla.org/en-US/Add-ons/WebExtensions) for your browser.
1+
# markdown-viewer
2+
3+
Markdown (.md file) Viewer [WebExtension](https://developer.mozilla.org/en-US/Add-ons/WebExtensions).
4+
Displays markdown documents beatified in your browser.
5+
6+
Markdown is a lightweight markup language which uses plain text to describe formatting information, such as `# Heading`, `1. numbered lists`, `**bold**`, etc.
7+
This add-on identifies markdown documents by the extension in the URL (one of .markdown, .md, .mdown, .mdwn, .mkd, .mkdn).
8+
When you navigate to a markdown document, if the content is plain text, not already styled (by GitHub for example), this add-on formats
9+
it into HTML (with headings, ordered lists, bold text, etc.) using markup from the document and displays it directly in your browser.
10+
11+
## Unicode Characters
12+
13+
So, non-ASCII characters in your document aren't displaying correctly? Special characters like " **á** " appear as " **á** "?
14+
This is a problem of character encoding, which concerns converting a file (a sequence of octets) into text (a sequence of characters) and back.
15+
By the time Firefox activates the Markdown Viewer Web Extension for your document, the file is already converted into text, correctly or incorrectly.
16+
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.
17+
Otherwise, Firefox may have decoded the file with the wrong encoding.
18+
Although UTF-8 is the modern _de facto_ standard encoding, Firefox defaults to using your system's regional encoding, yielding incorrect results.
19+
20+
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.
21+
Plus, this extension is intended to be a light and simple wrapper around the markdown-to-HTML converter, markdown-it.
22+
23+
When the markdown document is obtained from a web site, the site should return a Content-Type header which specifies the encoding.
24+
If it does not and the file lacks a BOM, you're out of luck. Contact the web site owner.
25+
26+
When the markdown is loaded from a local file, there are no HTML headers to lean on.
27+
Fortunately, Firefox now has a setting which allows specifying that you want to use UTF-8 for local files without a BOM.
28+
Go to about:config, search for `intl.charset.fallback.utf8_for_file`, and set its value to `true`. It should look better now.
29+
30+
## Viewing Original Markdown
31+
32+
To keep it simple, the extension does not support on and off states.
33+
If the document has one of the supported extensions, it should convert.
34+
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.
35+
36+
If you're viewing pretty markdown and you want to see the original source text, right-click and select "View Page Source".
37+
(Make sure you don't have any text selected to see that option.)
38+
Of course, you can also (Ctrl-S) save the document to a file and open it in any text editor.
39+
40+
## Saving Converted Markdown
41+
42+
If you would like to save the HTML-converted text, it is possible to do so in the desktop versions of Firefox.
43+
* Open developer tools with F12.
44+
* In the Inspector tab, select the `<html>` root element.
45+
* Right-click > Copy > Outer HTML.
46+
* Paste the text into your favorite text editor and save.
47+
48+
## Custom Appearance
49+
50+
You don't like how the styled markdown looks?
51+
Using CSS, you can customize the appearance any way you like it.
52+
View Add-ons (about:addons), and click Options for the Markdown Viewer.
53+
There is a box to enter your Custom CSS text. (Sorry, there is not currently a "user-friendly" drop-down option.)
54+
As the instructions there state, click or tab out of the text box to save your changes.
55+
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.
56+
If you have entered some changes that you don't want to keep, refresh the options page to discard changes.
57+
58+
For example to assign a maximum width root element in the styled markdown:
59+
60+
```css
61+
.markdownRoot {
62+
margin: 0 auto;
63+
max-width: 888px;
64+
padding: 45px;
65+
border: lightgrey thin solid;
66+
}
67+
```
68+
69+
## "Can You Add This Feature?"
70+
71+
This is an open-source project with the most liberal usage and change license there is.
72+
Please feel free to modify it to meet your needs, and to contribute your improvement back to the community.
73+
74+
Think only experts can do that?
75+
Although I am a programmer, I can only just make my way around JavaScript, and I'm a total beginner with the WebExtension browser plugin API.
76+
I needed a markdown viewer, and the plugin API which the existing add-on had used was deprecated and removed, so I adapted that add-on to the new technology.
77+
78+
I expect the feature set to grow, not from a single author, but by the contributions of users like you who need some additional capabilities.
79+
Several features have been added by community contributors who needed them, which include:
80+
81+
* checkbox support
82+
* anchored headers
83+
* reload maintaining scroll location
84+
* custom CSS
85+
86+
Many thanks to them and to our future contributors. Pull requests are welcomed.
87+
88+
## To Build The Extension
389

4-
## Build
590
* Required:
691
* [nodejs](https://nodejs.org/) with npm
792
* [web-ext](https://github.com/mozilla/web-ext/) (npm install -g web-ext)
893
* Run `build.bat` (Windows) or `build.sh` (Linux)
994

10-
## Test
11-
* (Firefox won't install the generated .zip unless it's signed by Mozilla; you can test from the staging folder.)
12-
* Navigate to the staging folder and run `web-ext run`.
13-
* Or install `staging/manifest.json` [temporarily in Firefox](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox).
95+
## To Test The Extension
96+
97+
Firefox won't install the generated `.zip` file permanently until it's signed by Mozilla.
98+
You can test any changes using the cloned project files.
99+
100+
* In a command prompt, navigate to the project root folder (containing the `manifest.json`) and run `web-ext run`.
101+
* Or to install the extension [temporarily in Firefox](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox):
102+
* First, uninstall this add-on if you have it already
103+
* Navigate to "about:debugging"
104+
* Click "Load Temporary Add-on"
105+
* Navigate to the project root folder and open the `manifest.json` file.

‎ext/background.js‎

Lines changed: 0 additions & 102 deletions
This file was deleted.

‎ext/content.js‎

Lines changed: 16 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
function addStylesheet(href, media) {
1+
const webext = typeof browser === 'undefined' ? chrome : browser;
2+
3+
function addStylesheet(href, media) {
24
var style = document.createElement('link');
35
style.rel = 'stylesheet';
46
style.type = 'text/css';
@@ -7,11 +9,11 @@
79
document.head.appendChild(style);
810
}
911
function addExtensionStylesheet(href, media) {
10-
addStylesheet(browser.extension.getURL(href), media);
12+
addStylesheet(webext.extension.getURL(href), media);
1113
}
1214

1315
function addCustomStylesheet() {
14-
browser.storage.sync.get('custom_css').then(storage => {
16+
webext.storage.sync.get('custom_css', (storage) => {
1517
if ('custom_css' in storage) {
1618
var style = document.createElement('style');
1719
style.textContent = storage.custom_css;
@@ -34,31 +36,30 @@ function makeAnchor(node) {
3436
anchor = anchor + '-' + i;
3537
}
3638
this.usedHeaders.push(anchor);
37-
console.log(node.textContent, '=>', anchor);
3839
node.id = anchor;
3940
}
4041

4142
function processMarkdown(textContent) {
4243
// Parse the content Markdown => HTML
43-
var md = markdownit({
44+
var md = window.markdownit({
4445
html: true,
4546
linkify: true,
4647
// Shameless copypasta https://github.com/markdown-it/markdown-it#syntax-highlighting
47-
highlight: function (str, lang) {
48-
if (lang && hljs.getLanguage(lang)) {
48+
highlight: (str, lang) => {
49+
if (lang && window.hljs.getLanguage(lang)) {
4950
try {
50-
return hljs.highlight(lang, str).value;
51+
return window.hljs.highlight(lang, str).value;
5152
} catch (__) {}
5253
}
5354

5455
try {
55-
return hljs.highlightAuto(str).value;
56+
return window.hljs.highlightAuto(str).value;
5657
} catch (__) {}
5758
return ''; // use external default escaping
5859
}
5960
})
6061
//markdown-it plugins:
61-
.use(markdownitCheckbox); //to format [ ] and [x]
62+
.use(window.markdownitCheckbox); //to format [ ] and [x]
6263

6364
var html = md.render(textContent);
6465

@@ -127,13 +128,7 @@ function processMarkdown(textContent) {
127128
document.body.appendChild(markdownRoot);
128129
}
129130

130-
function loadScriptThen(path, nextStep) {
131-
browser.runtime.sendMessage({ scriptToInject: path }, (response) => {
132-
if (response.success) { nextStep(); }
133-
});
134-
}
135-
136-
// Execute only if .md is unprocessed text.
131+
// Process only if document is unprocessed text.
137132
var body = document.body;
138133
if (body.childNodes.length === 1 &&
139134
body.children.length === 1 &&
@@ -147,14 +142,10 @@ if (body.childNodes.length === 1 &&
147142
if (hash > 0) url = url.substr(0, hash); // Exclude fragment id from key.
148143
var scrollPosKey = encodeURIComponent(url) + ".scrollPosition";
149144

150-
loadScriptThen('/lib/markdown-it/dist/markdown-it.min.js', () => {
151-
loadScriptThen('/lib/markdown-it-checkbox/dist/markdown-it-checkbox.min.js', () => {
152-
loadScriptThen('/lib/highlightjs/highlight.pack.min.js', () => {
153-
processMarkdown(textContent);
154-
window.scrollTo.apply(window, JSON.parse(sessionStorage[scrollPosKey] || '[0,0]'));
155-
})
156-
})
157-
});
145+
processMarkdown(textContent);
146+
try {
147+
window.scrollTo.apply(window, JSON.parse(sessionStorage[scrollPosKey] || '[0,0]'));
148+
} catch(err) {}
158149

159150
window.addEventListener("unload", () => {
160151
sessionStorage[scrollPosKey] = JSON.stringify([window.scrollX, window.scrollY]);

‎ext/markdown-mark-solid.svg‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎ext/markdown-mark-white.svg‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎ext/options.html‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,19 @@
55
<link rel="stylesheet" type="text/css" href="options.css" />
66
</head>
77
<body>
8-
<h3>Granted permissions</h3>
9-
<p><span id="all_origins">To enable markdown rendering for all websites, click the toolbar button from this page.</span></p>
10-
<p>Rendering Markdown is enabled on pages of the following domains (click to remove):</p>
11-
<ul id="origins"></ul>
12-
<p>Unfortunately, Firefox permissions do not allow Markdown rending for sites (like raw.githubusercontent.com) which return CORS headers.</p>
8+
<h3>Get Help</h3>
9+
<p>See this project's <a href="https://github.com/KeithLRobertson/markdown-viewer/blob/master/README.md">README</a> page for help with:</p>
10+
<ul>
11+
<li>Unicode characters not displaying correctly,</li>
12+
<li>how to customize styled markdown appearance,</li>
13+
<li>how to view the unstyled markdown text,</li>
14+
<li>and more.</li>
15+
</ul>
1316

1417
<h3>Custom CSS</h3>
15-
<p>If you enable syncing Add-ons with your Firefox account, the CSS will synchronize across your devices.</p>
1618
<p>Enter custom CSS to be applied to Markdown pages here.</p>
1719
<p>Click or tab out of the text area to save changes. Refresh this page to revert changes.<span id="saved" class="hidden"> &nbsp; &nbsp; SAVED</span></p>
20+
<p>If you enable syncing Add-ons with your <span id="browser_name">Firefox</span> account, the CSS will synchronize across your devices.</p>
1821
<textarea id="custom_css" style="margin: 10px; width:90%; min-height:30em;">Unable to load CSS from storage.</textarea>
1922

2023
<script src="options.js"></script>

0 commit comments

Comments
 (0)