Support partial file transclude about hercule

[zdne]

For what is worth we are working towards a referencing based on explicit ids – https://github.com/refractproject/refract-spec/blob/master/refract-spec.md#link-enum this is currently in the underlaying data format and not just yet in the API Blueprint itself.

[jamesramsay]

Thanks @zdne. That's useful to know.

[gautaz]

Are there any plans to support partial file transclude based on line numbers or regular expressions?

Supporting partial transclude based on markdown structure is in fact useful when transcluding markdown files but not when referencing source code parts for instance.

[jamesramsay]

@gautaz thanks for the input. No specific plans to add this at the moment, but this is primarily because I haven't had the need for it nor has anyone asked for it until now.

If there was significant interest from others too or if someone were to open a PR, I'd be happy to review, help out and merge a contribution adding this feature.

[gautaz]

My first concern about adding partial transclusion based on line numbers or regexes is the format of the markdown link.

To follow the initial proposal based on markdown sections, for line numbers, the format could be the one used by github:
:[link to something](sourcefile.lang#L32-L56)

For regexes, I am still wondering what would be the right format, perhaps something like:
:[link to something](sourcefile.lang#/start-regex/stop-regex/)

Feel free to add your own proposals.

[jamesramsay]

Sorry for reviving this old thread.

I've published a new version (4.0.0-beta.1) to npm which opens up a new API for resolving links. A resolve function basically receives the link portion of the transclusion link (file.md#section-6 of :[link to something](file.md#section-6)) and returns a stream or string to be transcluded.

If partial file transclusion is important the new API allows you to implement this by simply passing in your own function instead of the builtin resolvers.

[jamesramsay]

Closing, but happy to re-open in future if you want to discuss further.