concat-md

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

Usage

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

Features

• 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-links option is not enabled.
• Converts relative links to point to concatenated file,
• Works async (default) and sync.

CLI Options

1Usage
2  $ concat-md [options] <dir>
3
4Options
5  --ignore <globs csv>              - Glob patterns to exclude in 'dir'.
6  --toc                             - Adds table of the contents at the beginning of file.
7  --decrease-title-levels           - Whether to decrease levels of all titles in markdown file to set them below file and directory title levels.
8  --start-title-level-at <level no> - Level to start file and directory levels. Default: 1
9  --join-string <string>            - String to be used to join concatenated files. Default: new line
10  --title-key <key name>            - Key name to get title in 'FrontMatter' meta data in markdown headers.
11  --file-name-as-title              - Whether to use file names as titles.
12  --dir-name-as-title               - Whether to use directory names as titles.
13  --hide-anchor-links               - Do not add anchor links if optional titles are not set.
14  --debug                           - Print stack trace in errors.
15
16Examples
17  If files have titles in markdown already:
18    $ npx concat-md --toc --decrease-title-levels --dir-name-as-title typedoc-api-docs > README.md
19
20  If files have titles in FrontMatter meta data:
21    $ npx concat-md --toc --decrease-title-levels --title-key title --file-name-as-title --dir-name-as-title docs > README.md
22
23  If files don't have titles:
24    $ npx concat-md --toc --decrease-title-levels --file-name-as-title --dir-name-as-title docs > README.md

Example

└─ Development
   └─ Projects
      └─ project-a
         ├─ docs
         ├─ classes
         │  ├─ widget.md
         │  ├─ utility.md
         └─ interfaces
            └─ screen.md

classes/widget.md

1# Description
2
3Widget details lorem ipsum...

classes/utility.md

1# Description
2
3Utility details lorem ipsum...

interfaces/screen.md

1# Description
2
3Screen details lorem ipsum...

1$ md-merge --decrease-title-levels --file-name-as-title --dir-name-as-title docs > README.md

Above command;

• Concatenates markdown files,
• Adds directory names and file names as title,
• Decreases level of Description titles,
• Outputs to README.md as below:

README.md

1# Classes
2
3## Widget
4
5### Description
6
7Widget details lorem ipsum...
8
9## Utility
10
11### Description
12
13Utility details lorem ipsum...
14
15# Interfaces
16
17## Screen
18
19### Description
20
21Screen details lorem ipsum...

API

concat-md

Index

Interfaces

• ConcatOptions

Functions

• concatMd
• concatMdSync

Functions

concatMd

▸ concatMd(dir: string, options?: ConcatOptions): Promise<string>

Defined in index.ts:295

Scans and concatenates all markdown files in given directory.

Example

1import 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

▸ concatMdSync(dir: string, options?: ConcatOptions): string

Defined in index.ts:281

Scans and concatenates all markdown files in given directory.

Example

1import 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.

Interfaces

concat-md

ConcatOptions /

Interface: ConcatOptions

Concat function options.

Hierarchy

• ConcatOptions

Index

Properties

• decreaseTitleLevels
• dirNameAsTitle
• fileNameAsTitle
• hideAnchorLinks
• ignore
• joinString
• sorter
• startTitleLevelAt
• titleKey
• toc
• tocLevel

Properties

Optional decreaseTitleLevels

• 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.

---

Optional dirNameAsTitle

• dirNameAsTitle? : undefined | false | true

Defined in index.ts:72

Whether to use directory names as titles.

---

Optional fileNameAsTitle

• fileNameAsTitle? : undefined | false | true

Defined in index.ts:68

Whether to use file names as titles.

---

Optional hideAnchorLinks

• hideAnchorLinks? : undefined | false | true

Defined in index.ts:70

Do not add anchor links.

---

Optional ignore

• ignore? : string | string[]

Defined in index.ts:48

Glob patterns to exclude in dir.

---

Optional joinString

• joinString? : undefined | string

Defined in index.ts:60

String to be used to join concatenated files.

---

Optional sorter

• sorter? : undefined | (a: string, b: string) => number

Defined in index.ts:56

Custom sort function. If not set, files are sorted alphabetically.

---

Optional startTitleLevelAt

• startTitleLevelAt? : undefined | number

Defined in index.ts:56

Level to start file and directory levels.

---

Optional titleKey

• titleKey? : undefined | string

Defined in index.ts:64

Key name to get title in FrontMatter meta data in markdown headers.

---

Optional toc

• toc? : undefined | false | true

Defined in index.ts:40

Whether to add a table of contents.

---

Optional tocLevel

• tocLevel? : undefined | number

Defined in index.ts:44

Limit TOC entries to headings only up to the specified level.