Nimble Prime Musketeers

    @phoenix-plugin-registry/brackets-markdown-preview

    2.2.0 • Public • Published

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

    Downloads Downloads Downloads Downloads

    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

    Document Preview

    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.

    Document checkbox lists

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

      ```javascript
      // this code fragment should be highlighted
      function sayHello(){ alert('Hello syntax highlighting.'); }
      ```

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

      ```none
      // this code fragment won't be highlighted but is still recognizable as  "code"
      function sayBye(){ alert('Byebye syntax highlighting.'); }
      ```

      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:

    Open detached preview button

    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:

    Split view

    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

    Install

    npm i @phoenix-plugin-registry/brackets-markdown-preview

    DownloadsWeekly Downloads

    1

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    3.66 MB

    Total Files

    438

    Last publish

    Collaborators

    • ushmajit
    • core.ai