# markdown-content-blocks

> Parses content blocks into Markdown

Latest version **1.2.2** (published 2022-12-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install markdown-content-blocks
pnpm add markdown-content-blocks
yarn add markdown-content-blocks
bun add markdown-content-blocks
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2022-12-09 |
| First published | 2019-03-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 0 |
| Unpacked size | 10 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Anne Fortuin |
| Maintainers | phortuin |
| Keywords | markdown, content, block, content block, parse, replace, transclude, transclusion |

## Links

- npm: https://www.npmjs.com/package/markdown-content-blocks
- Repository: https://github.com/phortuin/markdown-content-blocks
- Issues: https://github.com/phortuin/markdown-content-blocks/issues
- npm.io page: https://npm.io/package/markdown-content-blocks

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.2.2 (latest) — 2022-12-09
- 1.2.1 — 2020-03-11
- 1.2.0 — 2020-03-10
- 1.1.0 — 2019-03-11
- 1.0.0 — 2019-03-11

## README

# markdown-content-blocks [![Build Status](https://travis-ci.org/phortuin/markdown-content-blocks.svg?branch=master)](https://travis-ci.org/phortuin/markdown-content-blocks)

> Parses content blocks into Markdown

Inspired by iA Writer’s content blocks, a file transclusion syntax for Markdown, as [specced here](https://github.com/iainc/Markdown-Content-Blocks).

## Install

```bash
$ npm install markdown-content-blocks
```

## Usage

```javascript
const contentBlocks = require('markdown-content-blocks')

let source = `
# Title

/example.js
/moretext.txt
/https://i.imgur.com/p66zLsr.jpg
/localimage.jpg
`

let blocks = {
	'example.js': `console.log('Hello World');`,
	'moretext.txt': 'Here be text'
}

let markdown = contentBlocks(source, blocks)

// # Title
//
// ```javascript
// console.log('Hello World');
// ```
//
// Here be text
//
// ![](https://i.imgur.com/p66zLsr.jpg "")
//
// ![](/localimage.jpg "")
```

## API

### contentBlocks(markdown, blocks, options?)

### contentBlocks.replace(markdown, blocks, options?)

Returns a Markdown string.

#### markdown

Type: `string`

Markdown string to be parsed.

#### blocks

Type: `object`

Key/value pairs where the key is the content block (a file name or path) that should be replaced; value is the replacement value:

```javascript
let blocks = {
	'example.js': `console.log('Hello World');`,
	'moretext.txt': 'Here be text'
}
```

#### options

Type: `object`

##### imagePath

Type: `string`  
Default: `/`

Sets the path that local images will be prefixed with. The image’s URI is prefixed as you configured it, so omit a leading slash for relative paths.

```javascript
let source = `
/myfamily.jpg
`

let markdown = contentBlocks(source, {}, { imagePath: 'images' })

// ![](images/myfamily.jpg "")
```

### contentBlocks.getBlocks(markdown)

Returns an array of content blocks (file names or paths) that were found in the given Markdown string.

**Note:** content blocks that appear to be images are ignored.

```javascript
let blocks = contentBlocks.getBlocks(source) //=> ['example.js', 'moretext.txt']
```

#### markdown

Type: `string`

## Notes

- Doesn’t embed `.csv` content blocks as tables
- Doesn’t syntax highlight everything mentioned in [iA’s spec](https://github.com/iainc/Markdown-Content-Blocks/blob/develop/Languages.json) (instead, it does most of what [Prism.js](https://prismjs.com/#languages-list) supports)
- Formats anything resembling an image URL (`/myimage.jpg`) as an image block and optionally empty title `![](/myimage.jpg "")`). No `alt` text is supported as of now; the iA Writer 'spec' is lacking in this regard.
- Ignores titles for code blocks, as there is no Markdown syntax for titles/captions for (fenced) code blocks. Same goes for text blocks (`.md` and `.txt`).

## License
[MIT](license) © [Anne Fortuin](https://phortuin.nl/)

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