@phoenix-plugin-registry/brackets-markdown-preview
Version:
Markdown live preview incl. detached window, code syntax highlighting, output themes, adaptive preview width, graphical checkboxes, activation on start...
221 lines (144 loc) • 14.7 kB
Markdown
# Brackets Markdown Preview
A [Brackets](https://github.com/adobe/brackets) extension that provides a live HTML preview of markdown documents, including code block syntax highlighting, themes, adaptive width, graphical checkboxes...
[](https://brackets-extension-badges.github.io#brackets-markdown-preview) [](https://brackets-extension-badges.github.io#brackets-markdown-preview) [](https://brackets-extension-badges.github.io#brackets-markdown-preview) [](https://brackets-extension-badges.github.io#brackets-markdown-preview)
## Features overview (Version 2.2.0)
* **NEW** detached preview panel to *display the preview independently from the main brackets window* (split) and to allow *direct printing* of the preview without the need of an external browser (see details below)
* **NEW** option to set the character encoding (default to 'utf-8') of the html output (within the preview panels)
* **NEW** enhanced the graphical checkbox to better display, regardless of the selected theme
* the keyboard shortcut `Ctrl-Alt-M` activates/deactivates the preview panel (see menu item `View -> Markdown Preview`)
* option to automatically activate the markdown preview when brackets is started (or when the extensions are reloaded e.g. using `F5`)
* improved user settings dialog to better display on narrowed preview panel, now using tabs to group settings
* the user settings dialog now respects the design theme selected for brackets itself (see menu item `View -> Designs...`)
* thin preview client document (loading highlight.js script in the preview isn't required anymore)
* code block syntax highlighting (based on _highlight.js_) including 77 CSS themes
* two different markdown format styles ("standard" and "GFM")
* seven different markdown CSS themes (including a _Github Markdown_ style)
* preview of markdown documents with extensions `*.markdown`, `*.mdown`, `*.mkdn`, `*.md`, `*.mkd`, `*.mdwn`, `*.mdtxt`, `*.mdtext`, `*.text`, `*.txt` and `*.Rmd`
* Yaml Frontmatter information headers are automatically parsed out prior to formating the document preview
* adaptive preview width is supported
* graphical checkboxes in (task) list items (checkboxes are readonly)
* option to sanitize anchors as defined by HTML5 [W3C recommandations](https://www.w3.org/TR/html5/text-level-semantics.html#the-a-element)
see also: [Roadmap/Changes](./ROADMAP.md)
**Important**:
the preview extension **never modify the edited markdown document**. Instead, it enhances and sanitizes the markdown input stream while parsing it, prior to the conversion in the preview (HTML) format.
Hence, this function is _not intended to correct any defect within the original markdown document_. Though it can be used - among other things - to check the final result of a conversion from the Markdown to the HTML format.
## Acknowledgment
This extension is based on the initial extension [markdown-preview](https://github.com/gruehle/MarkdownPreview) by Glenn Ruehle. Special thanks and initial license go to him.
## License
This extension is licensed under the **MIT License**. See the [LICENSE](./LICENSE) file for detailled information.
## Screenshot
# How to
## Installation
* Select **File > Extension Manager...** (or click the "brick" icon in the toolbar)
* Search for "Brackets Markdown Preview"
* Click the corresponding **Install** button
## Usage
### show/hide the preview
When a markdown document (with extension ".md", ".markdown" and so forth) is open, a markdown icon is shown in the toolbar at the top of the Brackets window. Click this icon to open the preview panel. The panel can be resized vertically.
The preview is updated as you edit the document. You can hover over links to see the href in a tooltip, or click them to open in your default browser.
### open/close the setting panel
Hover over the preview area to show the settings "gear" icon. Click this icon to change the settings.
## Configuration/Settings
Modifications of the settings are automatically persisted between two brackets sessions, even when the preview panel isn't visible. The settings are stored in the brackets preference file.
### Markdown Format
This extension supports previewing markdown as HTML. The HTML can be rendered according to two different format definitions: `Standard Markdown` and `GitHub Flavoured Markdown`.
By default/first usage, the document is rendered as `standard Markdown`. Change the dropdown value to `GitHub-Flavored (GFM)` in order to preview the Markdown as it would appear in a GitHub issue, pull request, or comment.
### Preview Theme
There are seven themes available:
* `Clean` - Black text on a light background, similar to GitHub wiki pages.
* `Dark` - Light text on a dark background.
* `Serif` - Black text with a serif font on a light background
* `Markdown5` - Kind of newspaper like theme displaying black on white serif fonts
* `Screen` - A dark brown theme with _wild west_ kind of headers
* `Markdown7` - similar to Markdown5 but using sans serif fonts but more striking syntax highlighting
* `Github` - A theme simulating the Github Markdown style
### Sync scroll position
When checked, scrolling in the editor scrolls the preview to roughly the same location. The scroll position of the preview is based on the scroll position of the source document, so the position may be out of sync if you have really long lines in your source file. Scroll synchronization works best when the preview and code view are the same height.
### Adaptive preview width
The selected CSS theme basically defines the layout of the preview. Hence, some CSS themes may define a text content area limited in width. This limitation can be overriden at some extent using the `Adaptive preview width` setting. When this option is "ON" i.e "checked", the text container should enlarge to 90% of the preview panel width. Resizing the Brackets window/panels will resize the text container according to this factor.
Note: Markdown defines different types of _line breaks_ (see markdown guidelines). The active markdown format also affects the way such line breaks are interpreted. Thus: **a consistent usage of line breaks is recommended!**
### Graphical checkbox (task) list
The textual representation of checkboxes (`[ ]`, `[x]`) within (task) lists is replaced by a graphical one (☐ / ☑ ) when this option is set.
Since this extension is intended to **preview** the edited markdown document as HTML, all graphical checkboxes are **readonly**! This way, the preview always stays in sync with the document. Hence, you'll have to edit the document in order to change the _checked_ state of a checkbox in the preview.
Update: the checkboxes are now displayed as html character entities and should reliably display, irrespective of the selected theme.
### Sanitize anchors (HTML5)
Some markdown documents make use of anchors in a way that doesn't match with the HTML5 recommandations. E.g.:
```html
<a title="THETITLE"/>
<a name="THENAME"/>
```
instead of
```html
<a title="THETITLE"></a>
<a id="THENAME"></a>
```
Hence, the extension allows to fix such anchors automatically:
* replacing the "_name_" attribute by the "_id_" attribute and
* ensuring the closing anchor tags won't be ommited.
**Notes**:
- Sanitizing may be usefull while editing/reviewing markdown documents using HTML in a format prior to HTML5. The preview should work without requiring modifications of the source document, albeit faulty.
- This simple sanitizing solution is optional and may fail in some case.
E.g. sanitizing an (HTML5 faulty) anchor having both "name" and "id" attributes set: the resulting anchor won't conform to the standard, since it will have two "id" attributes set.
The preview extension must not decide which of the IDs is correct. Instead, it's up to the document owner to fix by himself the faulty anchor within the markdown source file.
- The current implementation doesn't modify the behavior of the "marked" parser engine used to produce the preview. Instead, it fixes the markdown input stream prior to parsing it.
### Code block syntax highlighting
The extension makes use of the library `highlight.js` to provide syntax highlighting for code blocks. It also provides 77 syntax themes to choose from.
The supported languages are (at the moment):
> Apache, AppleScript, Arduino, AutoIt, Bash, C#, C++, CoffeeScript, CSS, Diff, Django, Dockerfile, DOS .bat, F#, Haskell, HTML, HTTP, Ini, Java, JavaScript, JSON, Makefile, Markdown, Nginx, Objective-C, Perl, PHP, PowerShell, Puppet, Python, Ruby, Shell Session, SQL, Swift, TypeScript, VB.NET, VBScript, XML, XQuery, YAML
**Notes**:
- Code syntax highlighting is applied to the full preview document prior to displaying it (highlight.js javascript library is not required in the preview document anymore):
While previewing _very large_ documents containing a lots of code and/or while editing documents on _not-so-fast environments_, this could have a negative impact on the refreshing rate of the preview. In such a case, it is recommended to disable highlighting using the configuration dialog while editing the source document. Re-enable to check the final result should be fair enough.
- Most of the **syntax highlighting themes** usually define a **background color**. Though, some of the **preview themes** may override this in order to enforce a specific background color. Please check different combinations of both theme settings to find a suitable one.
- In most cases, the supported languages should be recognized automatically by the highlighting library (error prone, though). In doubt, you may provide a specific **language alias name** to categorize a code block.
The list of _all_ aliases (incuding those supported in the preview) is available here: [http://highlightjs.readthedocs.io/...](http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html#language-names-and-aliases)
E.g.:
<pre>
```javascript
// this code fragment should be highlighted
function sayHello(){ alert('Hello syntax highlighting.'); }
```</pre>
should output to (highlighted)
```javascript
// this code fragment should be highlighted
function sayHello(){ alert('Hello syntax highlighting.'); }
```
- Marking a code fragment as such but without coloring/highlighting it is also supported (at least while using the GFM format mode), using the alias ```none``` (or any identifier, that is not recognized as a language alias).
E.g.:
<pre>
```none
// this code fragment won't be highlighted but is still recognizable as "code"
function sayBye(){ alert('Byebye syntax highlighting.'); }
```</pre>
should output to (not highlighted)
```none
// this code fragment won't be highlighted but is still recognizable as "code"
function sayBye(){ alert('Byebye syntax highlighting.'); }
```
### Activate markdown preview on start/reload
To avoid having to _manually_ activate the preview when brackets is started (or when the extensions are reloaded) you can choose to _automatically_ activate the preview by checking this option:
The preview panel will then be visible as soon as the edited document is a markdown or a text document.
**Note**:
if the current document isn't a markdown file, then the preview panel won't be visible, though the extension will be active if the option is checked and the preview panel will show up as soon as a markdown file is selected/displayed.
### Character encoding
An option within the setting dialog allows to set/override the character encoding (aka charset) of the preview html output. All standard encoding names (see [IANA Character Sets](https://www.iana.org/assignments/character-sets/character-sets.xhtml) ) are allowed. Unknown/incorrect charset names will enforce the browser window to use a fallback charset.
### Detached preview
A detached preview panel (supplemental window) is now available by clicking the corresponding button within the settings dialog:
The detached preview panel will stay in sync with the modifications of the edited document and also will react to switching to another document. At the present, the "scrolling synchronization" isn't implemented within the external preview, though other options impact on the window the same way as for the bottom preview panel.
Once the detached preview is open, you may arrange your main window and the detached preview to optimize your visual experience.
E.g. you may set the main brackets window to one side of your screen, activate the "No distraction mode" (by pressing CTRL+SHIFT+2 ) and then position the detached preview on the other side:
Note: activating the "**No distraction mode**" will temporary hide the preview panel at the bottom of the main window (also hiding the setting dialog), though the detached window will stay visible.
Note: the detached preview window allows to **print the preview** by using the context menu within the window and select "Print...". Though, the brackets internal print engine (chromium) may produce printouts of a lower quality as per using a standard standalone browser.
# Credits
This extension uses the following open source components:
* [markdown-preview](https://github.com/gruehle/MarkdownPreview) - the source of inspiration to this extension
* [Marked](https://github.com/chjj/marked) - A markdown parser written in JavaScript
* [markdown-css](https://github.com/sinnerschrader/markdown-css) - A Markdown css theme collection based on the "Swiss" theme
* [markdown-mark](https://github.com/dcurtis/markdown-mark) - The icon used in the toolbar
* [YAML](http://www.yaml.org/) - The official "YAML Ain't Markup Language" web site
* [github-markdown-css](https://github.com/sindresorhus/github-markdown-css) - The minimal amount of CSS to replicate the GitHub Markdown style
* [highlight.js](https://highlightjs.org/) - Syntax highlighting for the Web (174 languages and 77 styles...)
* [TinyColor.js](https://bgrins.github.io/TinyColor/) - Fast, small color manipulation and conversion for JavaScript