Feat: Enhance code snippets import continuation of #538

[ijpatricio]

Feature request

What problem does this feature solve?

When documenting an existing code project, if we later change some code on that, which is being imported on Vuepress docs, it gets out of sync!

So this Feature Request is extending more functionality on top of #538 (and somewhat similar to #612 but much simpler and more flexibility)

What does the proposed API look like?

Currently we have

import contents from somefile.js, bg highlight line 20, syntax highlight as file extension, i presume

<<< @/../project/somefile.js{20}

Proposition on #538 is

//to extract lines 1-10 from somefile.js, syntax highlight as js, and bg highlight lines 1 and 4

@[code{1-10} js{1,4}](../somefile.js)

That's great, and may continue to exist.

For making more dynamic approach, we could use "text-markers" (that could have * as wildcard :) )

// on somefile.js, 
// extract from first line that contains text 'some text',
// until first line that contains text 'another text'
// syntax highlight as js and bg highlight lines that contain 'myFuncName' or 'return someVar'

@[codesearch{'some text'-'another text'} js{'myFuncName','return someVar'}](../somefile.js)

if possible two more optional arguments (some code ommited for clarity)

// Preserve the line numbering matching the original file
// Means keep numbering 50-60 (like on imported file) instead of 1-11

@[codesearch  (...)     filenum{true}](../somefile.js)

// to the found markers, add padding top and bottom (that could be also negative numbers)
// say 'begin-mark' is line 50, start on 46, and if 'end-marker' is 60, finish on 58

@[codesearch (...)   padding{4, -2}](../somefile.js)

How should this be implemented in your opinion?

Pseudo-algorithm to implement it

find first occurence of 'some text', say this is originalLine=50, keep this as snippetLine=1
find first occurence of 'another text', say originalEndLine=60, snippetEndLine=11

if not both markers found, throw exception
if (originalEndLine - originalLine < 1) throw exception

highlight line with occurrence of `myFuncName()`
highlight line with occurrence of `return someVar`

Are you willing to work on this yourself?**

Yes I am. I will need some guidance with webpack related matters.

I do lots of stuff with VueJS for webapps, with SFC, started renderless components few weeks ago and so on... but webpack related, I don't have significant experience.

Going to clone and yarn link to try out locally, what goes on, try to hack something.

Would love to hear your feedback.

Thanks!

[ulivz]

Cool, thanks for creating this issue. let's work for that after 1.0.0 release.

[ijpatricio]

Cool, glad you like it. I had some problems on running with local "linked" directory, both with npm and yarn.. Could figure out very well.

Could find the file snippet.js, but need a little guidance to kick off.

So when it's time to do this, let me know!

Thanks!

[ijpatricio]

@ulivz may I sketch/prototype some examples of usage and expected output?

[colwilson]

Would it be an idea to allow snippets from the file which displays the snippet? This would mean that demo/howto examples could display the code which was used to create the rendered output without duplication.

[jthegedus]

Without the terms code fence or fencing or fragment in this thread it was difficult to find, so mentioning it now for other's future searching.

Docsify has an implementation of this as seen https://docsify.js.org/#/embed-files?id=embedded-code-fragments and I wanted to ask if anyone was working on this feature here?

[timaschew]

There is already a plugin: #1336
I've even tested it, it's working.

[jthegedus]

Too right. Wish it supported external sources like Docsify though!

[flozero]

As actually a plugin exist i am closing the issue. We will have a look about implement it in core thank's for your time all

[cloydlau]

It seems that plugin is out of maintenance. I mention it here that there's a mistake in the document of that plugin, it should be

  markdown: {
    plugins: ['markdown-it-vuepress-code-snippet-enhanced'],
  },

instead of

  markdown: {
    config: md => {
      md.use(require('markdown-it-vuepress-code-snippet-enhanced'))
    }
  },

The latter will render @[code](@/docs/code.js) as a link.

And one more thing, I use this plugin for *.md files, which is been rendered as highlighted plain text. So how can I make it render as true markdown?

[iamchriswick]

@cloydlau I don't think rending the output as a link is the intended function of this plugin. It is suppose to render a code block.