Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ozum/concat-md
CLI and API to concatenate markdown files and modify as necessary.
https://github.com/ozum/concat-md
Last synced: about 1 month ago
JSON representation
CLI and API to concatenate markdown files and modify as necessary.
- Host: GitHub
- URL: https://github.com/ozum/concat-md
- Owner: ozum
- License: mit
- Created: 2019-07-14T16:46:30.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-02-17T12:42:30.000Z (almost 2 years ago)
- Last Synced: 2024-05-14T06:21:59.555Z (7 months ago)
- Language: TypeScript
- Size: 703 KB
- Stars: 29
- Watchers: 2
- Forks: 6
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- project-awesome - ozum/concat-md - CLI and API to concatenate markdown files and modify as necessary. (TypeScript)
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 (``) 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]
Options
--ignore - 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 to start file and directory levels. Default: 1
--join-string - String to be used to join concatenated files. Default: new line
--title-key - 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
> **[concat-md](#readmemd)**
### Index
#### Interfaces
- [ConcatOptions](#interfacesconcatoptionsmd)
#### Functions
- [concatMd](#concatmd)
- [concatMdSync](#concatmdsync)
## Functions
### concatMd
▸ **concatMd**(`dir`: string, `options?`: [ConcatOptions](#interfacesconcatoptionsmd)): _`Promise`_
_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`_
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
> **[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.