CLI and API to concatenate markdown files and modify as necessary.
# Install
$ npm install -g concat-md
or use it via npx:
$ npx concat-md docs
If files have titles in markdown already:
$ concat-md --toc --decrease-title-levels --dir-name-as-title typedoc-api-docs > README.md
If files have titles in FrontMatter meta data:
$ concat-md --toc --decrease-title-levels --title-key title --file-name-as-title --dir-name-as-title docs > README.md
If files don't have titles:
$ concat-md --toc --decrease-title-levels --file-name-as-title --dir-name-as-title docs > README.md
- Scans all markdown files in a directory,
- Optionally ignores some files,
- Concatenates all of them,
- Adds table of contents,
- Optionally adds titles from
FrontMatter, file names and directory names, - Decreases level of existing titles to comply with added titles,
- Adds anchor tags (
<a name=""></a>) to files, if no optional titles are generated and the--hide-anchor-linksoption is not enabled. - Converts relative links to point to concatenated file,
- Works async (default) and sync.
Usage
$ concat-md [options] <dir>
Options
--ignore <globs csv> - Glob patterns to exclude in 'dir'.
--toc - Adds table of the contents at the beginning of file.
--decrease-title-levels - Whether to decrease levels of all titles in markdown file to set them below file and directory title levels.
--start-title-level-at <level no> - Level to start file and directory levels. Default: 1
--join-string <string> - String to be used to join concatenated files. Default: new line
--title-key <key name> - Key name to get title in 'FrontMatter' meta data in markdown headers.
--file-name-as-title - Whether to use file names as titles.
--dir-name-as-title - Whether to use directory names as titles.
--hide-anchor-links - Do not add anchor links if optional titles are not set.
--debug - Print stack trace in errors.
Examples
If files have titles in markdown already:
$ npx concat-md --toc --decrease-title-levels --dir-name-as-title typedoc-api-docs > README.md
If files have titles in FrontMatter meta data:
$ npx concat-md --toc --decrease-title-levels --title-key title --file-name-as-title --dir-name-as-title docs > README.md
If files don't have titles:
$ npx concat-md --toc --decrease-title-levels --file-name-as-title --dir-name-as-title docs > README.md└─ Development
└─ Projects
└─ project-a
├─ docs
├─ classes
│ ├─ widget.md
│ ├─ utility.md
└─ interfaces
└─ screen.md
classes/widget.md
# Description
Widget details lorem ipsum...classes/utility.md
# Description
Utility details lorem ipsum...interfaces/screen.md
# Description
Screen details lorem ipsum...$ md-merge --decrease-title-levels --file-name-as-title --dir-name-as-title docs > README.mdAbove command;
- Concatenates markdown files,
- Adds directory names and file names as title,
- Decreases level of
Descriptiontitles, - Outputs to
README.mdas below:
README.md
# Classes
## Widget
### Description
Widget details lorem ipsum...
## Utility
### Description
Utility details lorem ipsum...
# Interfaces
## Screen
### Description
Screen details lorem ipsum...▸ concatMd(dir: string, options?: ConcatOptions): Promise<string>
Defined in index.ts:295
Scans and concatenates all markdown files in given directory.
import concatMd, { concatMdSync } from "concat-md";Parameters:
| Name | Type | Description |
|---|---|---|
dir |
string | is the directory to scan markdown files in. |
options? |
ConcatOptions | are several parameters to modify concatenation behaviour. |
Returns: Promise<string>
concatenated contents of markdown files.
▸ concatMdSync(dir: string, options?: ConcatOptions): string
Defined in index.ts:281
Scans and concatenates all markdown files in given directory.
import concatMd, { concatMdSync } from "concat-md";Parameters:
| Name | Type | Description |
|---|---|---|
dir |
string | is the directory to scan markdown files in. |
options? |
ConcatOptions | are several parameters to modify concatenation behaviour. |
Returns: string
concatenated contents of markdown files.
Concat function options.
- ConcatOptions
- decreaseTitleLevels
- dirNameAsTitle
- fileNameAsTitle
- hideAnchorLinks
- ignore
- joinString
- sorter
- startTitleLevelAt
- titleKey
- toc
- tocLevel
• decreaseTitleLevels? : undefined | false | true
Defined in index.ts:52
Whether to decrease levels of all titles in markdown file to set them below file and directory title levels.
• dirNameAsTitle? : undefined | false | true
Defined in index.ts:72
Whether to use directory names as titles.
• fileNameAsTitle? : undefined | false | true
Defined in index.ts:68
Whether to use file names as titles.
• hideAnchorLinks? : undefined | false | true
Defined in index.ts:70
Do not add anchor links.
• ignore? : string | string[]
Defined in index.ts:48
Glob patterns to exclude in dir.
• joinString? : undefined | string
Defined in index.ts:60
String to be used to join concatenated files.
• sorter? : undefined | (a: string, b: string) => number
Defined in index.ts:56
Custom sort function. If not set, files are sorted alphabetically.
• startTitleLevelAt? : undefined | number
Defined in index.ts:56
Level to start file and directory levels.
• titleKey? : undefined | string
Defined in index.ts:64
Key name to get title in FrontMatter meta data in markdown headers.
• toc? : undefined | false | true
Defined in index.ts:40
Whether to add a table of contents.
• tocLevel? : undefined | number
Defined in index.ts:44
Limit TOC entries to headings only up to the specified level.