Advanced Configuration

Celso Miranda edited this page Dec 25, 2015 · 6 revisions

With hexo-renderer-markdown-it you're able to pass very specific configurations to the Markdown-it parser.

Available Settings (Explained)

html

The html setting defines whether or not HTML content inside the document should be escaped or passed to the final result.

html: true # Doesn't escape HTML content
    ## OR
html: false # Escapes HTML content so the tags will appear as text.

xhtmlOut

The xhtmlOut setting defines whether the parser will export fully XHTML compatible tags. This only needs to be true for complete [CommonMark] support.

xhtmlOut: true # Parser produces fully XHTML compliant code.
               # Ex: A line breaks will be <br />
    ## OR
xhtmlOut: false # Parser will not produce XHTML compliant code.
                # Ex: A line break will be <br>

breaks

Makes line breaks in the source file will be parsed into <br> tags. So every time you press the Enter key you will create a line break, which is not the default Markdown, CommonMark, or GFM behaviour.

breaks: true # Parser produces `<br>` tags every time there is a line break in the source document.
    ## OR
breaks: false # Parser will ignore line breaks in the source document.
              #Default double line break creates paragraph is still supported

linkify

The parser has the ability to inline links pasted directly into the text. If you write a piece of text that looks like a link it will be rendered as <a src="http://example.com">http://example.com</a>.

linkify: true # Returns text links as proper links inlined with the paragraph.
    ## OR
linkify: false # Returns text links as text.

typographer

This is enables the substitution for common typography elements like ©, curly quotes, dashes, etc.

typographer: true # Substitution of common typographical elements will take place.
    ## OR
typographer: false # No substitution, so dumb quotes will remain dumb quotes, etc.

quotes

Defines the double and single quotes used for substituting dumb quotes if typographer is set to true.

quotes: '“”‘’' # "double" will be turned into “single”
               # 'single' will be turned into ‘single’
    ## OR
quotes: '«»“”' # "double" will be turned into «single»
               # 'single' will be turned into “single”

Example configuration

# Markdown-it config
## Docs: https://github.com/celsomiranda/hexo-renderer-markdown-it/wiki
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: false
    linkify: true
    typographer: true
    quotes: '“”‘’'

Automatic Headline ID's

Enables you to automatically create ID's for the headings so you can link back to them. Since a valid html document can't have two elements with equal id's, every heading ID that is added will be checked against others already given.

If the title id is already given, this will change the subsequent ones to title-v2, title-v3, etc…

That v is the default collisionSuffix, which you can change.

Enable them in the global _config.yml like so:

markdown:
  anchors:
    # Minimum level for ID creation. (Ex. h2 to h6)
    level: 2
    # A suffix that is prepended to the number given if the ID is repeated.
    collisionSuffix: 'v'           
    # If `true`, creates an anchor tag with a permalink besides the heading.
    permalink: false              
    # Class used for the permalink anchor tag.
    permalinkClass: header-anchor 
    # The symbol used to make the permalink
    permalinkSymbol: 

Plugins

Available plugins:

  • markdown-it-abbr
  • markdown-it-footnote
  • markdown-it-ins
  • markdown-it-sub
  • markdown-it-sup

These can be enabled in the global _config.yml like so:

markdown:
  plugins:
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup

All options configuration

# Markdown-it config
## Docs: https://github.com/celsomiranda/hexo-renderer-markdown-it/wiki
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  plugins:
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup
  anchors:
    level: 2
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: header-anchor
    permalinkSymbol: 
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.