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

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

Example

└─ 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.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

# Classes

## Widget

### Description

Widget details lorem ipsum...

## Utility

### Description

Utility details lorem ipsum...

# Interfaces

## Screen

### Description

Screen 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

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

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

Defined in index.ts:281

Scans and concatenates all markdown files in given directory.

Example

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.

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.