CLI and API to concatenate markdown files and modify as necessary.
npm install concat-mdCLI 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 () 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.
`bash
Usage
$ concat-md [options]
Options
--ignore
--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
--join-string
--title-key
--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
`mdDescription
Widget details lorem ipsum...
`
classes/utility.md
`mdDescription
Utility details lorem ipsum...
`
interfaces/screen.md
`mdDescription
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,README.md
- Outputs to as below:
README.md
`mdClasses
Widget details lorem ipsum...
Utility details lorem ipsum...
Screen details lorem ipsum...
`
#### Interfaces
#### Functions
▸ concatMd(dir: string, options?: ConcatOptions): _Promise_
_Defined in index.ts:295_
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 | are several parameters to modify concatenation behaviour. |
Returns: _Promise_
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.
#### Example
`typescript`
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
#### Index
##### Properties
- decreaseTitleLevels
- dirNameAsTitle
- fileNameAsTitle
- hideAnchorLinks
- ignore
- joinString
- sorter
- startTitleLevelAt
- titleKey
- toc
- tocLevel
#### 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.
---
• 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.