sethen / markdown-include Goto Github PK

fs.readdirSync("./").filter(f => f.toLowerCase().endsWith(".json")).forEach(function(markdownJson) {
  markdownInclude.compileFiles(markdownJson).then(function () {
    console.info(markdownJson + ' have been built successfully');
  })
});

Example:
There are 3 JSON files in the directory with different files for compilation. But some of the MD files are reused in different compiled MD files.

1st.md content

#include my.md

2nd.md content

#include my.md
#include my2.md

3rd.md content

#include my.md
#include my3.md

my2.md content

some content about my2.
#include my3.md

every MD file has it's own unique Heading with !heading tag for inclusion into TOC.

This breaks the parse if & characters are in the title for the table of contents... Will have to follow Github guidelines on this.

The current code is written in ES5. The code should be overhauled with ES6 using Webpack or a similar compiler.

markdown-include should move to using TypeScript.

Great module. I dunno if this is the venue for this, but I haven't found another module that can do excerpts. For the purposes of this issue, I'm defining an excerpt as an include+delimiter. Seems fairly straightforward.

Any interest in that type of feature? I'd be happy to contribute if so.

Currently, markdown-include can pull in any type of file... It just looks at the path and goes from there. It should be smart enough to know when it's including a code snippet and wrap it with the appropriate code block for easier documentation. For instance, you could do

#include "ruby.rb"

And markdown-include should compile

class MyClass {
  def initialize(arg) {
     @arg = arg;
  }
}

wrapped in appropriate backticks that correspond to the language for syntax highlighting if available.

Hi, I was really hoping to use this in the browser. Is there any way it can be adapted for that? I'm already using several other markdown plugins client-side, so I hoped this would simply work.

If only level 3 or lower headings are included (using the !heading marker), the table of contents will be indented too much in the generated Markdown and the resulting HTML will not be a list.

This source file:

# Title
## Section
### Heading !heading
#### Subheading 1 !heading
#### Subheading 2 !heading

will result in this table of contents:

␣␣␣␣* [Heading](#heading)
␣␣␣␣␣␣* [Subheading 1](#subheading-1)
␣␣␣␣␣␣* [Subheading 2](#subheading-2)

(with the spaces represented by ␣)

If you have duplicate sub headings the link generated for them in the table of contents will just lead to the first match it finds. For instance, if you had:

# A Heading !heading
## A Subheading !heading

# Another Heading !heading
## A Subheading !heading

The table of contents generates the link based on the heading text. So both links for A Subheading would be the first subheading content.

If a filename includes a "." (separate from the ".md" extension), the file is not found/included and the string is left as-is.

//_readme.md

# A heading

Some text

#include "path/to/working/include.md"

More text

#include "path/to/other/include.5.md"

Resulting markdown:

# A heading

Some text

Some working markdown include

More text

#include "path/to/other/include.5.md"

A simple Suggestion,

After reading package.json, found the code is released under ISC License.

It would be nice if a separate licence file in repo and a hint at bottom of read file.

If acceptable, could make a PR 😄

Good Work <3

Thanks

If I specify build path to be 'folder-not-existed-yet/doc.md', the script will fail. I don't think this is a commonly expected behavior of a CLI tool though. As far as I've seen most build tools will create the build path if not existing already.

Using , character in headings that are built in the table of contents break the links.

At least on GitHub... I'm autogenerating the TOC and it thinks that the headings will include special characters, but GitHub strips them out. At a minimum, the following characters have broken the links my documentation:

• (
• )
• `
• .
• ,
• %

I think all of them should just be dropped, but I'm not 100% sure.

Having a dry mode for CI would be great 🙏

It would be nice if there was possibility to customize tag (I mean !heading) which tells whether specified heading is included in table of contents.

I have a case, when I compile a few markdown files into a single file and I'd like to have a TOC in resulting file, but at the same time I'm using the original file and I don't want !heading text to be visible in headings. With customization I could put tag inside comment and specify that TOC should contain headings marked with, for instance, <!-- !heading -->.

Currently, no back to top link exists with generated content. When content is generated, the user should have the option of adding one.

If no new lines are present at the bottom of individual markdown files, the parser will get confused and just concatenate them as they are. This breaks titles that may be present in other files.