concat-md

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