# concat-md

> CLI and API to concatenate markdown files and modify as necessary.

Latest version **0.5.1** (published 2023-02-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install concat-md
pnpm add concat-md
yarn add concat-md
bun add concat-md
```

Provides the command `concat-md`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.1 |
| Published | 2023-02-17 |
| First published | 2019-07-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10.8.0 |
| Dependencies | 6 |
| Unpacked size | 38.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 34 |
| Author | Özüm Eldoğan |
| Maintainers | ozum |
| Keywords | concat, concatenate, merge, join, markdown, md, generator, creator, README, README.md, TypeDoc, JSDoc, FrontMatter, Meta, cms |

## Links

- npm: https://www.npmjs.com/package/concat-md
- Repository: https://github.com/ozum/concat-md
- Homepage: https://github.com/ozum/concat-md#readme
- Issues: https://github.com/ozum/concat-md/issues
- npm.io page: https://npm.io/package/concat-md

## Dependencies (6)

- [meow](https://npm.io/package/meow.md) ^9.0.0
- [doctoc](https://npm.io/package/doctoc.md) ^2.2.1
- [globby](https://npm.io/package/globby.md) ^11.1.0
- [front-matter](https://npm.io/package/front-matter.md) ^4.0.2
- [lodash.startcase](https://npm.io/package/lodash.startcase.md) ^4.4.0
- [transform-markdown-links](https://npm.io/package/transform-markdown-links.md) ^2.0.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.5.1 (latest) — 2023-02-17
- 0.5.0 — 2022-08-11
- 0.4.0 — 2022-04-08
- 0.3.8 — 2022-02-25
- 0.3.6 — 2022-02-25
- 0.3.5 — 2020-05-08
- 0.3.4 — 2020-05-05
- 0.3.3 — 2020-05-05
- 0.3.2 — 2019-10-15
- 0.3.1 — 2019-10-15
- 0.3.0 — 2019-07-16
- 0.2.1 — 2019-07-16
- 0.2.0 — 2019-07-15
- 0.1.0 — 2019-07-14
- 0.0.1 — 2019-07-14

## README

# 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

```bash
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**

```md
# Description

Widget details lorem ipsum...
```

**classes/utility.md**

```md
# Description

Utility details lorem ipsum...
```

**interfaces/screen.md**

```md
# Description

Screen details lorem ipsum...
```

```bash
$ 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**

```md
# Classes

## Widget

### Description

Widget details lorem ipsum...

## Utility

### Description

Utility details lorem ipsum...

# Interfaces

## Screen

### Description

Screen details lorem ipsum...
```

# API

<a name="readmemd"></a>

> **[concat-md](#readmemd)**

### Index

#### Interfaces

- [ConcatOptions](#interfacesconcatoptionsmd)

#### Functions

- [concatMd](#concatmd)
- [concatMdSync](#concatmdsync)

## Functions

### concatMd

▸ **concatMd**(`dir`: string, `options?`: [ConcatOptions](#interfacesconcatoptionsmd)): _`Promise<string>`_

_Defined in [index.ts:295](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L295)_

Scans and concatenates all markdown files in given directory.

#### Example

```typescript
import concatMd, { concatMdSync } from "concat-md";
```

**Parameters:**

| Name       | Type                                        | Description                                               |
| ---------- | ------------------------------------------- | --------------------------------------------------------- |
| `dir`      | string                                      | is the directory to scan markdown files in.               |
| `options?` | [ConcatOptions](#interfacesconcatoptionsmd) | are several parameters to modify concatenation behaviour. |

**Returns:** _`Promise<string>`_

concatenated contents of markdown files.

---

### concatMdSync

▸ **concatMdSync**(`dir`: string, `options?`: [ConcatOptions](#interfacesconcatoptionsmd)): _string_

_Defined in [index.ts:281](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L281)_

Scans and concatenates all markdown files in given directory.

#### Example

```typescript
import concatMd, { concatMdSync } from "concat-md";
```

**Parameters:**

| Name       | Type                                        | Description                                               |
| ---------- | ------------------------------------------- | --------------------------------------------------------- |
| `dir`      | string                                      | is the directory to scan markdown files in.               |
| `options?` | [ConcatOptions](#interfacesconcatoptionsmd) | are several parameters to modify concatenation behaviour. |

**Returns:** _string_

concatenated contents of markdown files.

# Interfaces

<a name="interfacesconcatoptionsmd"></a>

> **[concat-md](#readmemd)**

[ConcatOptions](#interfacesconcatoptionsmd) /

## Interface: ConcatOptions

Concat function options.

### Hierarchy

- **ConcatOptions**

#### Index

##### Properties

- [decreaseTitleLevels](#optional-decreasetitlelevels)
- [dirNameAsTitle](#optional-dirnameastitle)
- [fileNameAsTitle](#optional-filenameastitle)
- [hideAnchorLinks](#optional-hideanchorlinks)
- [ignore](#optional-ignore)
- [joinString](#optional-joinstring)
- [sorter](#optional-sorter)
- [startTitleLevelAt](#optional-starttitlelevelat)
- [titleKey](#optional-titlekey)
- [toc](#optional-toc)
- [tocLevel](#optional-toclevel)

### Properties

#### `Optional` decreaseTitleLevels

• **decreaseTitleLevels**? : _undefined | false | true_

_Defined in [index.ts:52](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L52)_

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](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L72)_

Whether to use directory names as titles.

---

#### `Optional` fileNameAsTitle

• **fileNameAsTitle**? : _undefined | false | true_

_Defined in [index.ts:68](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L68)_

Whether to use file names as titles.

---

#### `Optional` hideAnchorLinks

• **hideAnchorLinks**? : _undefined | false | true_

_Defined in [index.ts:70](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L70)_

Do not add anchor links.

---

#### `Optional` ignore

• **ignore**? : _string | string[]_

_Defined in [index.ts:48](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L48)_

Glob patterns to exclude in `dir`.

---

#### `Optional` joinString

• **joinString**? : _undefined | string_

_Defined in [index.ts:60](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L60)_

String to be used to join concatenated files.

---

### `Optional` sorter

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

*Defined in [index.ts:56](https://github.com/ozum/concat-md/blob/3cf72b4/src/index.ts#L82)*

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

___

#### `Optional` startTitleLevelAt

• **startTitleLevelAt**? : _undefined | number_

_Defined in [index.ts:56](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L56)_

Level to start file and directory levels.

---

#### `Optional` titleKey

• **titleKey**? : _undefined | string_

_Defined in [index.ts:64](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L64)_

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

---

#### `Optional` toc

• **toc**? : _undefined | false | true_

_Defined in [index.ts:40](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L40)_

Whether to add a table of contents.

---

#### `Optional` tocLevel

• **tocLevel**? : _undefined | number_

_Defined in [index.ts:44](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L44)_

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

---
_Source: https://npm.io/package/concat-md · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._