ember-cli-marked-down

This addon provides a means to generate html formatted markup from markdown source. The ShowdownJS library is leveraged to generate the html and this addon has been designed to be globally configured at the application's environment.js level.

It is worth mentioning that Markdown was created by John Gruber and the ShowdownJS library was authored by John Fraser and is a vanilla port of Gruber's original works.

Compatibility

Ember.js v3.12 or above
Ember CLI v2.13 or above
Node.js v10 or above

Installation

ember install ember-cli-marked-down

Demo

Check out the demo application.

Cross-Side Scripting (XSS) Vulnerability

Notice: this addon will be converting Markdown source in the client (browser). The produced HTML is passed to Ember.String.htmlSafe(...) to attempt to filter any XSS attempts. This is not fool-proof. Know your user audience and assume all risks.

ShowdownJS

Check out ShowdownJS's wiki post about XSS for additional information.

Usage

Helpers

`{{marked-down "Some markdown text"}}`

The helper that produces html from the supplied markdown. Override Showdown's options by passing named arguments to the helper.

Arguments

The markdown source String is the only unnamed argument passed into the helper.
Use the helper's hash to supply all other markdown options that need be applied to the cooked html. See the options listed above in the ShowdownJS Configuration section.

Examples

{{marked-down 'Some __markdown__ text'}}

...yields:

<p>Some <strong>markdown</strong> text</p>

Passing in a Showdown option:

{{marked-down 'Some ~~struck~~ markdown text' strikethrough=true}}

...yields

<p>Some <del>struck</del> markdown text</p>

Components

`{{set-links-target}}`

This component surrounds some html markup, searches the surrounded markup for <a> elements (links), and then proceeds to add a specified target attribute to the link should it not already have a target.

The component by default will not assign the target attribute to links that it finds that belong to the host that the application is running in. That is to say, if an app is running at http://example.com and the component find a link that starts with http://example.com, then that link will NOT have a target attribute assigned. This default behaviour can be overridden by setting the excludeSelfLinks? argument to false.

Arguments

excludeSelfLinks? - when true (DEFAULT) any links that are found in the component's yield that share the same host url as the Ember application will NOT have the target attribute assigned. When false all found links will have the target attribute assigned.
targetValue - one of the valid target values that can be passed to the target attribute of an anchor/link element. One of: _blank, _self, _parent, _top, or the name of a frame in the page. See W3Schools reference.

Examples

Default Behaviour:

{{#set-links-target excludeSelfLinks?=true targetValue='_blank'}}
  <a href='http://github.com'>GitHub</a>
{{/set-links-target}}

... will result in the following html markup:

<div class="set-links-target">
  <a href="http://github.com" target="_blank">GitHub</a>
</div>

Services

`ShowdownConverter`

This service sets the Showdown libraries globals from the environment.js settings; see the sample configuration above.

Initializers

`ShowdownConverter`

An initializer that makes sure the ShowdownConverter service is initialized for all scopes. This forces the Showdown globals to be set to the settings found in the environment.js.

ShowdownJS Configuration (Optional)

Inside the Ember application's config/environment.js, set ShowdownJS' global option preferences. Use the following example as a template:

// config/environment.js

module.exports = function (environment) {
  var ENV = {
    // ...
    APP: {
      // ...
      /**
       * Showdown global configuration settings.
       * @see https://github.com/showdownjs/showdown#valid-options
       */
      showdown: {
        /**
         * (boolean) [default false] Omit the trailing newline in a code block.
         */
        omitExtraWLInCodeBlocks: false,
        /**
         * (boolean) [default false] Disable the automatic generation of header ids. Setting to true
         * overrides prefixHeaderId
         */
        noHeaderId: false,
        /**
         * (boolean) [default false] Generate header ids compatible with github style (spaces are
         * replaced with dashes and a bunch of non alphanumeric chars are removed) (since showdown-1.5.5).
         */
        ghCompatibleHeaderId: false,
        /**
         * (string/boolean) [default false] Add a prefix to the generated header ids. Passing a
         * string will prefix that string to the header id. Setting to true will add a generic 'section' prefix.
         */
        prefixHeaderId: false,
        /**
         * (boolean) [default false] Enable support for setting image dimensions from within markdown syntax.
         */
        parseImgDimensions: false,
        /**
         * (integer) [default 1] Set the header starting level.
         */
        headerLevelStart: 1,
        /**
         * (boolean) [default false] Turning this on will enable GFM autolink style.
         */
        simplifiedAutoLink: false,
        /**
         * (boolean) [default false] This option excludes trailing punctuation from
         * autolinking urls. Punctuation excluded: . ! ? ( ). Only applies if
         * simplifiedAutoLink option is set to true.
         */
        excludeTrailingPunctuationFromURLs: false,
        /**
         * (boolean) [default false] Turning this on will stop showdown from interpreting underscores
         * in the middle of words as <em> and <strong> and instead treat them as literal underscores.
         */
        literalMidWordUnderscores: false,
        /**
         * (boolean) [default false] Enable support for strikethrough syntax.
         */
        strikethrough: false,
        /**
         * (boolean) [default false] Enable support for tables syntax.
         */
        tables: false,
        /**
         * (boolean) [default false] If enabled adds an id property to table headers tags.
         */
        tablesHeaderId: false,
        /**
         * (boolean) [default true] Enable support for GFM code block style.
         */
        ghCodeBlocks: true,
        /**
         * (boolean) [default false] Enable support for GFM takslists.
         */
        tasklists: false,
        /**
         * (boolean) [default false] Prevents weird effects in live previews due to incomplete input.
         */
        smoothLivePreview: false,
        /**
         * (boolean) [default false] Tries to smartly fix indentation problems related to es6
         * template strings in the midst of indented code.
         */
        smartIndentationFix: false,
        /**
         * (boolean) [default false] Disables the requirement of indenting sublists by
         * 4 spaces for them to be nested, effectively reverting to the old behavior where
         * 2 or 3 spaces were enough. (since showdown-1.5.0).
         */
        disableForced4SpacesIndentedSublists: false,
        /**
         * (boolean) [default false] Parses line breaks as like GitHub does, without
         * needing 2 spaces at the end of the line (since showdown-1.5.1).
         */
        simpleLineBreaks: false,
        /**
         * (boolean) [default false] Makes adding a space between # and the header text
         * mandatory (since showdown-1.5.3).
         */
        requireSpaceBeforeHeadingText: false,
        /**
         * (boolean) [default false] Enables github @mentions, which link to the username
         * mentioned (since showdown-1.6.0).
         */
        ghMentions: false,
      },
    },
  };
  // ...
  return ENV;
};

License

This project is licensed under the MIT License.