md-in-place

CAUTION: To avoid unintentional irreversible loss of sections of your markdown file, read and understand the documentation before using this node module. The library is not battle tested. Use on your own risk. However I have personally used it to create the README.md files of my own projects and have not encountered any unwanted results.

Table of contents
Installation
Description
Code coverage
Example
Documentation
Best practices
Contributing
- How it works
- Limitations
FAQs
Acknowledgments
Changelog
- 1.0.1
- 1.0.0
- 0.2.0
- 0.1.0
- 0.0.1
- 0.0.0
License

Installation

npm install --save-dev md-in-place

Description

Node.js CLI executable that enables imports for markdown files.

Code coverage

Testing code coverage is around 90%.

Example

Create a new folder and set it as your current working directory:
```
mkdir example; cd ./example;
```
Initialize the folder as an npm package and install md-in-place as a development dependency:
```
npm init -y;
npm install --save-dev md-in-place;
```

Create the file ./README.md with the following content:

# Example

## Table of contents

<!--#region toc-->

<!--#endregion toc-->

## Documentation

<!--#region my-custom-keyword ./documentation.md-->

<!--#endregion my-custom-keyword-->


<!--#region my-other-custom-keyword !./documentation.ts-->

<!--#endregion my-other-custom-keyword-->

Create the file ./documentation.ts with the following content:
```
export const a: number = 1;
```
Create the file ./documentation.md with the following content:
```
Hello world!
```

Execute:

npx md-in-place

Now the ./README.md file should have the following content:

# Example

## Table of contents

<!--#region toc-->

- [Table of contents](#table-of-contents)
- [Documentation](#documentation)

<!--#endregion toc-->

## Documentation

<!--#region my-custom-keyword ./documentation.md-->

Hello world!

<!--#endregion my-custom-keyword-->


<!--#region my-other-custom-keyword !./documentation.ts-->

```ts
export const a: number = 1;
```

<!--#endregion my-other-custom-keyword-->

Documentation

Use:

npx md-in-place --help

to get the cli documentation:

CLI syntax:

  md-in-place mdInPlace? [[--<option> | -<flag>] <value>]#

Description:

  Injects in place the provided github flavoured markdown, with file imports
  and auto generated toc.

Non required options:

  -i --input : string = "./README.md"  Path to the markdown file.

Toc generation

The place to inject the auto generated toc is specified via special HTML comments:

CAUTION: Everything between these two comments gets irreversibly deleted on toc injection.
```



```
Both markdown and HTML headings are taken into account when creating the toc.
Headings inside markdown or HTML code blocks are ignored.
Headings from imported files are also taken into account.

File injection

The place to inject an imported file is specified via special HTML comments:

CAUTION: Everything between these two comments gets irreversibly deleted on file injection.
```



```
The keyword can be any word you choose as long as the starting and ending comment have the same keyword.
For relative path that starts with exclamation mark:
```



```
the injected file is wrapped in markdown code block (the one with the three back ticks) with the same extension as the injected file extension. Adding more exclamation marks will add more back ticks. This is something useful when the injected file is a markdown file with code blocks.

Links with relative paths

If any markdown or html link has relative path, the program will throw error. The idea behind that is that relative links will not work for both npm and and github.

Best practices

The special comments can be collapsed in vscode. Keep them always collapsed to avoid editing their content.

Add two empty lines before and after each special comment.

Good

<!--#region toc-->

<!--#endregion toc-->

Bad

<!--#region toc-->
<!--#endregion toc-->

Try to use the program only at the distribution stage. Avoid using it in the development stage.
After you have edited the markdown file, make sure you have saved it before using the program.

Contributing

I am open to suggestions/pull request to improve this program.

You will find the following commands useful:

Clones the github repository of this project:

git clone https://github.com/lillallol/md-in-place

Installs the node modules (nothing will work without them):
```
npm install
```
Tests the code and generates code coverage:
```
npm run test
```
The generated code coverage is saved in ./coverage.
Lints the source folder using typescript and eslint:
```
npm run lint
```
Builds the typescript code from the ./src folder to javascript code in ./dist:
```
npm run build-ts
```
Creates the CLI executable of this program in ./bin/bin.js:
```
npm run build-bin
```
Make sure that the ./dist exists when you execute this command, otherwise it will not work.
Injects in place the generated toc and imported files to README.md:
```
npm run build-md
```
Make sure that ./bin/bin.js exists when you execute this command, otherwise it will not work.
Checks the project for spelling mistakes:
```
npm run spell-check
```
Take a look at the related configuration ./cspell.json.
Checks ./src for dead typescript files:
```
npm run dead-files
```
Take a look at the related configuration ./unimportedrc.json.

How it works

The markdown file is parsed to abstract syntax tree (ast) using remark. The ast consists of markdown and html fragments that include information such as:

source code
line relative to the markdown file
offset start relative to the markdown file
offset end relative to the markdown file

The markdown fragments are converted to html and together with the rest of the html fragments are searched using jsdom, for anchor tags, comments and headings.

Limitations

Validation for:
- path of file to be imported
is too strict. Open an issue so I can improve it.
Empty lines define the beginning and end of html fragments. That can potentially lead to unexpected results. For example this markdown fragment:
```
<details>
<summary>Some summary</summary>
</details>
```
is parsed as a single html fragment, while this:
```
<details>
<summary>Some summary</summary>

</details>
```
is parsed as two html fragments because of the line that separates them.

FAQs

Can you add a feature for collapsible toc?

I have already written the code for such a feature, but I have disabled it. That is because the margins of such a toc are not uniform. If people still show interest I am willing to enable this feature.

Acknowledgments

This program would not be possible without remark and jsdom.

Changelog

1.0.1

bug fixes

The text of the links in the toc have their trailing space characters removed, now. Not removing this white space was causing issues with prettier markdown formatter.

1.0.0

breaking changes

Updated fn-to-cli version. That means that now instead of passing "./path/to/markdown.md", you have to pass "'./path/to/markdown.md'".

non breaking changes

Heading of depth 1 is not taken into account when generating the toc.
HTML headings are now converted to ids for the toc, the same way markdown headings are.
The program now works with headings with the same text.
The program now allows any character in the headings text.

bug fixes

fixed a bug when converting heading text to id (white spaces were wrongly removed).

other

added documentation for the CLI in README.md

0.2.0

non breaking changes:

Markdown headings are now converted to ids for the toc, in accordance to the information provided in this link.

0.1.0