@gerhobbelt/markdown-it-code-snippet-enhanced

Markdown-it Code Snippet Enhanced

Why use this plugin?

• Specify your own language :boom:
• Transclude any part of a file :boom:
• prism-based extended Line highlighting :green_heart:

Install

npm i -D @gerhobbelt/markdown-it-code-snippet-enhanced

Setup

In Vuepress config.js add the following:

markdown: {
    config: md => {
        md.use(require('@gerhobbelt/markdown-it-code-snippet-enhanced'))
    }
}

You can now import code snippets into your markdown files with the following syntax:

@code
@code lang=ruby transclude={1-1}
@code highlight={1-6} transcludeTag=style
@code highlight={4,9,11-16} transcludeWith=:::

Plugin configuration options

{
  root: <path represented by '@'> (default: process.cwd())
  throwOnError: boolean (default: true)
}

e.g.

import markdownit from '@gerhobbelt/markdown-it';
import codeSnippetPlugin from '@gerhobbelt/markdown-it-code-snippet-enhanced';

...

const md = markdownit({ linkify: true })
            .use(codeSnippetPlugin, {
              root: __dirname,
              throwOnError: true
            });

let html = md.render(md_text, env);

Markdown Options

Language

You can specify any language for syntax highlighting as follows:

@code lang=ruby
@code lang=csharp

highlight assumes your markdown rig uses prismjs, so for proper syntax highlighting check prism.js docs.

Transclusion

You can transclude a single or multiple parts of a file using transclude, transcludeWith, transcludeAuto, or transcludeTag.

transcludeWith

For transcluding one or more parts of a file, specify a unique pattern.

@code lang=ruby transcludeWith=|_|_|
@code transcludeWith=:::
@code transcludeWith=++++

Example 1

require 'lib'  
require 'other'  

# |_|_|
def hello
  puts 'hello'
  puts 'vue'
end
# |_|_|

Example 2 (Illustrating multiple transclusions in the same file)

require 'lib'  
require 'other'  

# |_|_|
def hello
  puts 'hello'
  puts 'vue'
end
# |_|_|

   ... more code ...

# |_|_|
def goodebye
  puts 'bye...'
end
# |_|_|

transcludeTag

Useful when working Vue single file components.

@code transcludeTag=template
@code transcludeTag=script
@code transcludeTag=style

transcludeAuto

This matches any comment which carries the given marker:

@code transcludeAuto=|_|

transclude

Use a range indicating the start and end lines. This option is inclusive.

Ranges can be compound, using , or | (depending on your preference) to separate sub-ranges and single lines, e.g.:

@code transclude={5-8|19|21-24|29-31|35|37}

Note that the range brackets are optional and arbitrary: these next two examples specify the exact same compound range:

@code transclude=5-8|19|21-24|29-31|35|37

@code transclude=START:5-8|19|21-24|29-31|35|37:END

In fact, any characters not matching the [\\d|,-] regex set are simply disscarded before the transclude range is parsed.

Sample

Input Markdown

@code highlight={1-6} transcludeTag=style

Source File

<template>
  <div class="component"></div>
</template>

<script>
export default {
  mounted () {
    alert('yay!')
  }
}
</script>

<style lang="scss" scoped>
.component {
  display: flex;
}
</style>

Rendered Output

<style lang="scss" scoped>
.component {
  display: flex;
}
</style>