feat: Add support to import files as code fence

[znck]

Add rule to import code snippets:

...
## Minimal

rollup-plugin-vue ships as zero config solution to package `.vue` files.

<<< @/cookbook/minimal/rollup.config.js{1,10}

[Akryum]

snippet?

[ulivz]

LGTM, would you please also add the tests for that?

[ulivz]

same here

[ulivz]

Final thing, could you also document for this feature? thanks!

[znck]

I feel it should support importing given lines from large a file but that can be a different PR.

[ulivz]

Awesome! welcome to open any PRs for good stuffs like this.

[octref]

I wish we could do a syntax more inline with markdown and Vue loaders, for example:

# My Config

<code src="@/cookbook/minimal/rollup.config.js"></code>
<code src="@/cookbook/minimal/rollup.config.js" start="1" end="10"></code>

This is both valid markdown, and benefits include:

• Editor can support syntax highlight easily
• Editor might be able to linkify the src and offer jump-to-definition
• The code is now semantic. <<< is much less straight-forward and readable than <code>
• Following spec is always a good thing.

[ulivz]

@octref Looks good to me, but for now there are some restrictions for us to implement above syntax:

Since our md's process pipeline is markdown loader => vue loader, and markdown loader is responsible for highlight and other code-related transpliation, so all code must be included before it was thrown to Vue Loader.

So for the above grammar, we need to implement a simple XML parser at markdown's side which looks too complicated.

I just have an idea, which is simple, semantic enough and also offer jump-to-definition:

[code{1-2}](../app.js)

[octref]

@ulivz That's actually quite a nice idea. I was about to suggest https://github.com/iainc/Markdown-Content-Blocks which would solve the problem of file transcultion in general.

One problem is code there actually don't mean anything. The other problem (also with the original proposal) is that {1-2} or {1, 10} is very misleading...I thought it was open/end but it was actually lines that need highlight. But I don't have a good idea now either.

[znck]

@octref's concerns are valid. Let's give this problem another shot.

What do we need:

• Transclusion (full or partial)
• Line highlighting
• Performed statically & within scope of markdown loader

@yyx990803 Any suggestions here?

---

https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270
(It's listed on proposed commonmark extensions)

[znck]

Something like https://github.com/posva/markdown-it-custom-block could be better here.

:[code](../somefile.js)
:[code {1,4}](../somefile.js)
:[code js{1,4}](../somefile.js)
:[code js{1,4}](../somefile.js "1-10") <!-- Partial Transclusion -->

It would support explicit language, line highlighting and with click jumping editor support.

@octref WDYT?

[ulivz]

@znck I like it. but how about this syntax for partial transclusion?

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

It prevent the links from being changed and still offer jump-to-definition.

[znck]

I'll send a PR by EOD.

[octref]

I think the highlight line syntax need more thought. Can you do things like {2-5,8-10} for ranges?
On the other hand I wouldn’t find partial transclution very useful or ergonomic. When I go to the transcluded file I don’t know which part is included without looking at the importing file. Also if I only want line 2-5 why don’t I delete line 1? If Line 1 is necessary why not just highlight line 2-5?

[znck]

If you have a large file and you want to import only couple of lines. Example importing only script from SFC.

[octref]

Well you can also remove other lines in the source file, if they are not relevant.
Maybe you are thinking in one project, you can import in /doc/index.md something from /src/Component.vue, etc. But those are very implicit dependencies and I don't think that's a real need.

[daggerok]

Hey, so can anybody tell me if some time in a future we will have possibility to include partially code snippets or it wont be possible for some religion reasons?

Write really good documentation which is updating together with code is very important. let's say I have some class and important business method in it. So It would be awesome to tell vuepress include code only (for example) from comment with start-lable to comment with ending label.
Asciidoctor has that possibility and it's very handy. Here example how I can include only interested code range from file (snippet-1 label) right from real source code file (not from it's copy, snippet for documentation needs):

codeWontBeIncluded();
// tag::snippet-1
myBusinessMethod();
myOtherImportantCode();
// end::snippet-1
otherCodeWontBeIncluded();

so If I will add some more important code in between myBusinessMethod() and myOtherImportantCode() my documentation will be successfully updated automatically. But if I will be using separate snippet-files I can even forget about it and documentation will be inconsistent and developers should do more effort to keep documentation updated. As you can see, @octref it's not useless case

Guys, please add such possibility, we really needed it
for now we are using this awesome md enhancer: #1336 (comment) but it's really what we need

Thanks

---

Regards,
Maksim