Added support for embedding fragments with <!-- [fragment] --> syntax

[tannerntannern]

Summary

Embedding file snippets via /// [snippet] is a very powerful feature, but it currently doesn't work well with markdown or HTML snippets. I added a third option, <!-- [snippet] -->, to deal with this problem and modified the relevant docs.

I hate to make things difficult for the reviewers... but I got endless errors trying to build the project on my Windows machine, so I was not able to test or build the project. I did test my regex additions separately though. If someone could independently test this, it would be much appreciated. Here's an example to make it easy:

# Markdown file
Here is a snippet from another file:
[snippet](./another-markdown-file.md ':include :fragment=snippet')

# Another markdown file
blah blah blah
<!-- [snippet] -->
This is a fragment from another markdown file
<!-- [snippet] -->
blah blah blah

What kind of change does this PR introduce? (check at least one)

• Bugfix
• Feature
• Code style update
• Refactor
• Docs
• Build-related changes
• Other, please describe:

If changing the UI of default theme, please provide the before/after screenshot:

Does this PR introduce a breaking change? (check one)

• Yes
• No

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

• When resolving a specific issue, it's referenced in the PR's title (e.g. fix #xxx[,#xxx], where "xxx" is the issue number)

You have tested in the following browsers: (Providing a detailed version will be better.)

• Chrome
• Firefox
• Safari
• Edge
• IE

If adding a new feature, the PR's description includes:

• A convincing reason for adding this feature
• Related documents have been updated
• Related tests have been updated

To avoid wasting your time, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

---

• DO NOT include files inside lib directory.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[anikethsaha]

cc @timaschew @trusktr can you review this ?
DO we want this ?

[arelstone]

This can come in really handy..

@tannerntannern could you please fix the conflight with master and then lets cross fingers for this getting merged. To verify that this works you should also add some tests for this

💯 💘

[trusktr]

I like this syntax better than the existing syntax options. 👍 @tannerntannern Mind resolving the conflict?

[tannerntannern]

Thanks @arelstone and @trusktr. I resolved the conflicts but I've been struggling to add proper tests, not knowing the repository well. I've been trying to get something working in test/unit/renderer.test.js, because there didn't seem to be any existing tests for embedding, but I couldn't figure out how to get the docsify compiler to actually embed files for testing. Here's what I was working on for reference:

describe('embed', function() {
  it('/// [syntax]', async function() {
    const { docsify } = await init();

    expectSameDom(
      docsify.compiler.compile(
        'Here is some JS: "[filename](../fixtures/embed/slash-syntax/embed1.js \':include :type=code :fragment=fragment\')"'
      ),
      '<p>Here is some JS: "const foo = \'bar\';"</p>'
    );
  });

  it('### [syntax]', async function() {
    // TODO
  });

  it('<!-- [syntax] -->', async function() {
    // TODO
  });
});

Any guidance is appreciated.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.