Skip to content
/ concat-md Public

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

License

Notifications You must be signed in to change notification settings

ozum/concat-md

Repository files navigation

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

Functions

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

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.

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published