Brackets Markdown Preview

A Brackets extension that provides a live HTML preview of markdown documents, including code block syntax highlighting, themes, adaptive width, graphical checkboxes...

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

see also: Roadmap/Changes

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 by Glenn Ruehle. Special thanks and initial license go to him.

License

This extension is licensed under the MIT License. See the 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.:

<a title="THETITLE"/>
<a name="THENAME"/>

instead of

<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/...

  E.g.:

  should output to (highlighted)

  // 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.:

  should output to (not highlighted)

  // 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 ) 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 - the source of inspiration to this extension
• Marked - A markdown parser written in JavaScript
• markdown-css - A Markdown css theme collection based on the "Swiss" theme
• markdown-mark - The icon used in the toolbar
• YAML - The official "YAML Ain't Markup Language" web site
• github-markdown-css - The minimal amount of CSS to replicate the GitHub Markdown style
• highlight.js - Syntax highlighting for the Web (174 languages and 77 styles...)
• TinyColor.js - Fast, small color manipulation and conversion for JavaScript