Git Product home page Git Product logo

markdown-viewer's Introduction

Markdown Viewer / Browser Extension

Install: Chrome / Firefox / Edge / Opera / Brave / Chromium / Vivaldi

Features

  • Secure by design
  • Render local and remote file URLs
  • Granular access to remote origins
  • Multiple markdown parsers
  • Full control over the compiler options (markdown-it, marked, remark)
  • 30+ Themes (cleanrmd, GitHub)
  • Custom theme support
  • GitHub Flavored Markdown (GFM)
  • Auto reload on file change
  • Syntax highlighted code blocks (prism)
  • Table of Contents (ToC)
  • MathJax formulas (mathjax)
  • Mermaid diagrams (mermaid)
  • Convert emoji shortnames (icons provided free by EmojiOne)
  • Remember scroll position
  • Markdown Content-Type detection
  • Configurable Markdown file path detection
  • Settings synchronization
  • Raw and rendered markdown views
  • Free and Open Source

Table of Contents

Additional documentation specific to Firefox

After Install

Local Files

  1. Navigate to chrome://extensions
  2. Locate the Markdown Viewer extension and click on the Details button

img-extensions

  1. Make sure that the Allow access to file URLs switch is turned on

img-file-access

Remote Files

  1. Click on the Markdown Viewer icon and select Advanced Options
  2. Add the origins that you want enabled for the Markdown Viewer extension

Themes

All themes support the following width options:

  • auto - automatically adjust the content width based on the screen size
  • full - 100% screen width
  • wide - fixed at 1400px
  • large - fixed at 1200px
  • medium - fixed at 992px
  • small - fixed at 768px
  • tiny - fixed at 576px

The auto option on the github and github-dark themes has a fixed width with a surrounding border identical to a rendered README.md file for a repository hosted on github.com

Custom Theme

  1. Go to the Advanced Options and click on Settings
  2. Select CUSTOM for Content Theme
  3. Upload your Custom Theme below
  4. Specify the Color Scheme of your theme

Your custom theme will be minified automatically on upload and it can be up to 8KB in size.

You can add <link rel="stylesheet" type="text/css" href="file:///home/me/custom-theme.css"> to your markdown document to speed up development while working on your theme. Custom theme example.


Compiler Options

Full CommonMark support including GFM tables and strikethrough +

Option Default Description
abbr false Abbreviation using *[word]: Text <abbr>
attr false Custom attributes using {} curly brackets
breaks false Convert new lines \n in paragraphs into line breaks <br>
cjk false Suppress linebreaks between east asian characters
deflist false Definition list <dl>
footnote false Footnotes [^1] [^1]: a
html true Enable HTML tags in source
ins false Inserted text ++a++ <ins>
linkify true Autoconvert URL-like text to links
mark false Marked text ==a== <mark>
sub false Subscript ~a~ <sub>
sup false Superscript ^a^ <sup>
tasklists false Task lists - [x]
typographer false Enable some language-neutral replacement + quotes beautification
xhtmlOut false Use / to close single tags (<br />)

Content Options

Option Default Description
autoreload false Auto reload on file change
emoji false Convert emoji :shortnames: into EmojiOne images
mathjax false Render MathJax formulas
mermaid false Render Mermaid diagrams
syntax true Syntax highlighted fenced code blocks
toc false Generate Table of Contents

Autoreload

When enabled the extension will make a GET request every second to markdown files hosted on:

  • file:/// URLs
  • any host that resolves to localhost IPv4 127.0.0.1 or IPv6 ::1

Emoji

Convert emoji :shortnames: into EmojiOne images:

  • Emoji shortnames like :smile: will be converted to 😄 using EmojiOne images.
  • Currently unicode symbols like 😄 and ASCII emoji like :D are not supported.

MathJax

The following MathJax delimiters are supported:

  • inline math: \(math\) and $math$
  • display math: \[math\] and $$math$$

The following rules apply to your markdown content when MathJax is enabled:

  • Regular dollar sign $ in text that is not part of a math formula should be escaped: \$
  • Regular markdown escaping for parentheses: \( and \), and brackets: \[ and \] is not supported. MathJax will convert anything between these delimiters to math formulas, unless they are wrapped in backticks: `\(` or fenced code blocks.

Mermaid

Render Mermaid diagrams wrapped in mmd or mermaid fenced code blocks:

```mmd
sequenceDiagram
```

Alternatively diagrams can be wrapped in HTML tags:

<pre><code class="mermaid">
  sequenceDiagram
</code></pre>
  • resize the diagram container vertically by dragging the bottom right corner of the code block up or down
  • zoom in and out by holding down the Shift key and then using your mouse wheel
  • pan by holding down the left mouse button and drag in any direction

Syntax

Syntax highlighting for fenced code blocks:

```js
var hello = 'hi'
```

Alternatively code blocks can be wrapped in HTML tags:

<pre class="language-js"><code class="language-js">var hello = 'hi'</code></pre>

Full list of supported languages and their corresponding aliases to use.

ToC

Generates Table of Contents (ToC) based on the headers found in the markdown document.


Manage Origins

Click on the Markdown Viewer icon and select Advanced Options.

By default Markdown Viewer does not have access to any content:

img-no-access

Enable File Access

To enable access to file URLs follow these steps.

In case access to local files was not enabled, an additional Allow Access button will be present next to the File Access header:

img-file-access-allow

Clicking on it will point you to the built-in management page for the extension where you can toggle the Allow access to file URLs switch to enable it.

Enable Site Access

Access to individual sites can be enabled by copy/pasting a URL address into the Site Access text box and then clicking on the Add button next to it:

img-site-access-add

Access to both http and https protocols can be enabled by using a wildcard *://raw.githubusercontent.com

Access to all subdomains for a given hostname can be enabled by using a wildcard https://*.githubusercontent.com

Access to all ports on localhost can be enabled by adding http://localhost. Access to a specific port can be enabled by adding http://localhost:3000

Allow on All Sites

Access to all sites can be enabled by clicking on the Allow All button next to the Site Access header:

img-site-allow-all

This is identical to adding the *://* pattern into the text box.

Content Detection

Each enabled origin has an option for content type header detection and path matching regular expression:

img-site-access-enabled

Header Detection

When this option is enabled the extension will check if the content-type header with a value of text/markdown, text/x-markdown or text/plain is present.

Path Matching

When this option is enabled the extension will check if the page URL matches the Path Matching RegExp.

The default regular expression is: \.(?:markdown|mdown|mkdn|md|mkd|mdwn|mdtxt|mdtext|text)(?:#.*|\?.*)?$

It is a simple regular expression that matches URLs ending with:

  • markdown file extension: \.(?:markdown|mdown|mkdn|md|mkd|mdwn|mdtxt|mdtext|text)
  • and optionally a hash or a querystring after that: (?:#.*|\?.*)?

The ?: used in (?:match) stands for non-capturing group and it is there for performance reasons.

You can modify the path matching regular expression for each enabled origin. The settings are being updated as you type.

Path Matching Priority

The enabled origins are matched from most to least specific:

  1. https://raw.githubusercontent.com
  2. https://*.githubusercontent.com
  3. *://raw.githubusercontent.com
  4. *://*.githubusercontent.com
  5. *://*

The matching origin with the highest priority will be picked and its header detection and path matching settings will be used to determine if the content should be rendered or not.

It is recommended to explicitly allow only the origins that you want the extension to have access to.

Remove Origin

Click on the Remove button for the origin that you want to remove. This removes the permission itself so that the extension can no longer access that origin.

Refresh Origin

The extension synchronizes your preferences across all of your devices if you have logged into your browser and enabled the sync feature. The list of your allowed origins is being synced too. However, the actual permissions that you grant using the consent popup cannot be synced.

In case you have enabled a new origin on some of your devices you will have to explicitly allow it on your other devices. In this case the origin will be highlighted and an additional Refresh button will be present:

img-site-refresh

Only origins that needs to be refreshed will be highlighted. The extension cannot access highlighted origins unless you click on the Refresh button.

In some cases access to previously allowed origins may get disabled. Make sure you check back the advanced options page or reload it and look for highlighted origins that needs to be refreshed.


Syntax Examples

Examples about the Markdown syntax and all features available in Markdown Viewer can be found on GitHub, GitLab and BitBucket:

  • elements.md - quick overview of the Markdown syntax and a summary of the Markdown Viewer features
  • syntax.md - extensive list of Markdown syntax examples with different combinations and edge cases
  • prism.md - syntax highlighting examples
  • mermaid.md - different types of Mermaid diagrams
  • mathjax.md - MathJax examples and support documentation

Allow the appropriate remote origin or pull any of the above repositories and access it on the file:/// origin locally.


Manual Install

The following instructions applies for: Chrome, Edge, Opera, Brave, Chromium and Vivaldi.

Note that in any of the following cases you won't receive any future updates automatically!

Load packed .crx

  1. Go to releases and pick a release that you want to install
  2. Download the markdown-viewer.crx file
  3. Navigate to chrome://extensions
  4. Drag and drop the markdown-viewer.crx file into the chrome://extensions page

Load unpacked .zip

  1. Go to releases and pick a release that you want to install
  2. Download the markdown-viewer.zip file and extract it
  3. Navigate to chrome://extensions
  4. Make sure that the Developer mode switch is enabled
  5. Click on the Load unpacked button and select the extracted directory

Build

  1. Clone this repository
  2. Execute sh build/package.sh chrome (or firefox to build for Firefox)
  3. Navigate to chrome://extensions
  4. Make sure that the Developer mode switch is enabled
  5. Click on the Load unpacked button and select the cloned directory

Manifest v2

  1. Clone the mv2 or compilers-mv2 branch (Markdown Viewer v4.0)
  2. Navigate to chrome://extensions
  3. Make sure that the Developer mode switch is enabled
  4. Click on the Load unpacked button and select the cloned directory

License

The MIT License (MIT)

Copyright (c) 2013-present, Simeon Velichkov [email protected] (https://github.com/simov/markdown-viewer)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

markdown-viewer's People

Contributors

disfated avatar jmckiern avatar simov avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

markdown-viewer's Issues

Remember the scroller's position

Is it possible to remember the scroller's position of the current tab before processing. At the moment I'm using your extension but when I have a long markdown file and refresh the page I'm losing my position.

Steps to reproduce:

  • open long markdown file
  • scroll down to the bottom of the page
  • refresh the page
  • you are positioned in the top

Custom Stylesheets

First of all, I'd like to thank you for developing this extension. It seems to be the best of the Markdown Viewers available on the Chrome Web Store.

One feature which I wish was supported is custom stylesheets. The provided themes are great, but I wish I could tweak the CSS on a couple of them to suit my preferences. I think there would be demand for this from other users too, given Markdown's popularity among developers.

Are you open to contributions on this? If so, I could try to implement something over the next couple of weeks and submit a pull request.

Thanks,
David

Mathjax support

I'm using markdown to take notes on machine learning, which requires a good few formulae.

Can this plugin support MathJax?

Export XHTML file that preview the same as rendered file

I try finding a simple way export Readable document from markdown, until I meet this markdown viewer. However, the PDF file saved from chrome has some problem with styling. (for example, the margin line with page breakings seem not so beautiful, and some table's style also missed for some themes), so if there is a way to export a XHThtml file that get all js, images tables in a file, the plugin will be the perfect one!

here are some requirements:

  • usable toc and anchor
  • included images(svg, png, jpg etc.) in the exported file
  • same style tables as rendered( will be perfect if all thing get the same as rendered page)

TOC not supporting non-ascii characters

When headers in the .md file consist no alphanumeric characters, the TOC falls back to generate anchor link of '#-'.
This results in multiple TOC items jump to the same content, whence is the first occurrence of the non-alphanumeric header.
Maybe consider adding auto prefixes to the generated anchor link to mitigate this issue?

UTF-8 default

Could you make UTF the default encoding for HTML preview? Or at least an option to set it.
Things like
image
would then display like
image

Support for font-awesome

When I try to rewrite my latex resume with markdown, I think ti's a beautifiation to add some font-awesome icons in the resume, however I found the plugin not has the supportment. Is it a good idea add font-awesome support? If so, I'll take it in hand.

YAML metadata + TOC, Marked compiler

At times, MarkDown documents come with additional YAML metadata at the beginning of a document. This is often referred to as a frontmatter and is indicated by triple dashes in the first line and after the YAML keys.

Currently the Marked compiler renders it as a horizontal rule, the raw data structures written out and a third-level headline in the beginning of the document and as such the false headline also at the beginning of the Table of Contents (ToC).

Add support for checkboxes

I often use checkboxes in my Markdown, which are supported in Github markdown:

  • Item

It would be nice if markdown-viewer also supported them!

Possibility to **exclude** some domains from "Allow all"?

I’d like to principally “allow all” matching URLs but I’d like to exclude those on github.com, because Github includes .md etc. in regular URLs, e.g. https://github.com/simov/markdown-viewer/blob/master/README.md is a HTML document, and if I enable “Allow all” then the extension is trying to process it, leading to odd results (some items are badly shifted).

I see that it’s not possible to use regexes in the domain section of the options, right? I tried ^(?:(?!github\.com)) but the extension didn’t add this pattern to the list.

Chinese characters in title are ignored when content table is generated

If There is a title which contains both latin letters and chinese characters such as "三级标题 h3 in chinese", only the english part is converted into an HTML internal link. The URL is like:

file:///file_path/markdown_viewer_bug_test.md#-h3-in-chinese

Try this file:
markdown_viewer_bug_test.md.zip

Generally, to handle chinese character we need to do encoding in UTF-8. For example,
https://zh.wikipedia.org/wiki/万维网联盟
is actually
https://zh.wikipedia.org/wiki/%E4%B8%87%E7%BB%B4%E7%BD%91%E8%81%94%E7%9B%9F

ignores <pre> tags

I have the following <pre> tag:

     src /
        content/
        images/
        scripts/
        styles/
     
     templates/
        partials/ 

In Chrome, the markdown-viewer extension renders a flat string:

<pre> src / content/ images/ scripts/ styles/ templates/ partials/ </pre>

Whereas, the same <pre> tags renders perfectly when posted to github.

id and anchor not work, when heading not include English or Number

id and anchor not work, when heading not include English or Number.
sidebar jumping not work too.

example:

# 测试一
## 测试二
### 测试三

output

<div id="html" class="markdown-body">
    <h1 id="-">测试一</h1>
    <h2 id="-">测试二</h2>
    <h3 id="-">测试三</h3>
</div>

<div id="_toc">
    <div id="_ul">
        <a href="#-">测试一</a>
        <div id="_ul">
            <a href="#-">测试二</a>
            <div id="_ul">
                <a href="#-">测试三</a>
            </div>
        </div>
    </div>
</div>

Better regex for raw.githubusercontent.com

With private Github repos, when I click on the Raw button for any Markdown document, the URL that is formed looks like this:

https://raw.githubusercontent.com/user/repo/master/README.md?token=xxxxxxxxxxxx

I’ve modified the regex so that it catches the ? after the .md extension. This works well:

\.(?:markdown|mdown|mkdn|md|mkd|mdwn|mdtxt|mdtext|text)(?:#.*|\?.*)?$

Perhaps you’d be willing to improve the defaults in the extension? It’s fantastic anyway!

Back anchor in footnote can have a better style

as in the picture below, the back anchor start in a new line:
image

what about make it appear at the end of relevant footnote like this:
image

I think minor change will make it more clear about which footnote the back anchor goes.

PS: I was using remark for rendering

Match gitlab readme

gitlab readmes are matched by your app, would be nice if you add gitlab to exclude_matches in manifest json

Exclude list

Would be great to have an exclude list, like it's implemented on plugins like AdBlock "Exclude this site/domain".

Tables' indentation doesn't work

case 0: a table at indentation level 0, after a paragraph (at level 0) -- this should render the table not-indented

A B
1 2
  • case 1: a table at indentation level 1, after a list item at level 1 -- this should render the table indented once

    A B
    1 2
    • case 2: a table at indentation level 2, after a list item at level 2 -- this should render the table indented twice

      A B
      1 2

case 3: a table at indentation level 1, after a a paragraph (at level 0) -- this should render the raw text into a code block

|A|B|
|---|---|
|1|2|

Add print styling

Thanks for writing this great plugin! It's great for previewing markdown files. I also use it to convert markdown to PDF, using the print functionality of my browser. Unfortunately, there aren't any print styles in the themes. This adds a border to the GitHub theme, as Huangjj27 noted in #36. It also creates awkward page-breaks, which can be really annoying.

I would greatly appreciate any improvement in this area.

Handling as ‘escape’ issue about the parenthesis ‘)’

We are currently running with Chrome extension and
I personally think this is a great and useful function.

In the case of
[Monit](https://192.168.2.141:20080/failsafe\(monit\).md)

it’s not handling as escape due to there’s
Monit.md)
exist.

Thank you.

Firefox version can't open .md file from file system

It may be the behaviour priority of firefox 57(default to give me a choice to save the file or to open it with other local that causes the unrecognizing of such files.

and from the issue #12, I know that the firefox version does still not to get local markdown file rendered. When will it get support?

image

TOC - GitHub theme - 1st level headline CSS, Marked compiler

The Marked compiler renders first level headlines (lines starting with a single #) as raw (blue) HTML links into the Table of Contents outline. This may be due to #29. Remark doesn't show this behaviour, either.

Only the GitHub and GitHub dark themes are affected.

Hot reload changes to markdown file

My main use case for this extension has been to preview markdown files under development. It would be incredibly useful to have an option that would enable the plugin to rerender the file if the file has been changed.

As an alternative, rather than attempting to detect file changes, the extension can also rerender based on some period (1 second, 5, second) set by the user.

round brackets not works in urls

example

[bla](bla(bla).md)

result

bla.md)

Of course I can use %28 and %29 instead ( and ) in urls, but title in browser will be incorrect

Markdown Checkbox support broken.

You should be able to us - [ ] to create a todo list action, but it does not render it properly.

Expected:

  • Like this

Actual:

  • [ ] Like this

Handle `text/markdown` documents (on any URL)

The current method of enabling this viewer on non-localhost URLs (via the options pane) is cumbersome and doesn't scale well. For example, I'd like to publish a markdown page for project documentation. While I'm okay saying, "This page requires the Markdown Viewer", I'm not okay saying "... and then go to options, the url for this site, then change the regex to ...(obscure regex here)...". That's just... gnarly.

I'd like to see an option (or default) for this viewer to handle any page served with Content-Type: text/markdown. This is the de-facto standard, and the IETF has published an informational spec, which I assume lends some degree of legitimacy to this mime type.

Thoughts?

HTML comments show up

I use HTML comments <!-- --> to add comments to my markdown. These shouldn't show up in the HTML preview as those are HTML comments. They don't show up on github.com, but does show up in preview generated by markdown-viewer.

Markdown

# Vim and NeoVim

## Table of Contents

<!-- vim-markdown-toc GFM -->
* [Vim](#vim)
* [NeoVim](#neovim)
    * [Building](#building)
    * [C/C++ Support](#cc-support)

<!-- vim-markdown-toc -->

Preview

Vim and NeoVim

Table of Contents

<!-- vim-markdown-toc GFM -->
- Vim
- NeoVim
    - Building
    - C/C++ Support
<!-- vim-markdown-toc -->

Reload on file change

Hallo,

What do you think about a feature to reload files automatically when it changes in the background?
An alternative would be to reload (or check) the file in a fixed time interval.

Kind regards,
Dirk

pre/code not formatted properly with some theme

With some theme, the pre/code section that starts with 4 spaces are all squashed to the left edge, ignoring the space characters inside.

One of such theme is GODSPEED. Themes like GHOSTWRITER works as expected.

Support for ToC themes

The Remark compiler does not apply the selected theme to the Table of Contents. The Marked compiler however applies it partly, and only for first level headlines, which are presented as links.

Lower levels unfortunately do not inherit a theme's font setting in any way.

Custom style sheets

Would it be possible to add an option to override specific CSS rules in a chosen theme?

For example, I'd like to be able to specify a maximum width for images, while using the default GitHub theme. A field in the advanced options, where I could enter my own CSS, would allow me to achieve this:

.markdown-body img {
    max-width: 20em;
}

The .markdown-body class selector would be required to override the specificity of the default stylesheet (which is annoying and confusing), however just appending this CSS to the end of the selected theme style sheet would be all that's required to get it working.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.