extract-frontmatter 1.0.3

A library that allows a user to extract an arbitrary number of lines of "front-matter" from the start of any string.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# Table of Contents <!-- omit in toc -->

- [Overview](#overview)
  - [Versioning](#versioning)
- [Configuration](#configuration)
  - [Example](#example)

# Overview

A library that allows a user to extract an arbitrary number of lines of "frontmatter" from the start of any multiline string.

Included is some basic auto-detection of what lines are considered to be part of the frontmatter, but erroneous detection can be prevented by tuning the configuration.

Note that absolutely no parsing of extracted frontmatter is performed; this is designed to output its results for another library to then parse.

## Versioning

This project follows [Semantic Versioning principals](https://semver.org/) starting with `v1.0.0`

# Configuration

| Setting         | Type            | Description                                                                                                                                                                                |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `number`        | `Option<usize>` | The exact number of lines to extract, ignoring `end_line`; omit for auto-detection based on `end_line` or consecutive lines of `lead_chars`                                                |
| `end_line`      | `Option<&str>`  | Treat the first occurrence of this string (alone on a line except for `lead_chars`) as the end of frontmatter                                                                              |
| `lead_chars`    | `Option<&str>`  | Strip this string from the start of extracted frontmatter lines; consecutive lines starting with this string are treated as frontmatter lines if `number` and `end_line` are not specified |
| `discard_first` | `bool`          | Whether or not to discard the entire first line that is extracted                                                                                                                          |

## Example

Given a variable `input` with the following text:

```md
<!--
parent:
  - item1
  - item2
-->

# Title

This is an example markdown document.
```

... and the following code:

```rust
use extract_frontmatter::{Config, extract};
let config = Config::new(None, Some("-->"), None, true);
let output = extract(&config, input);
```

... the variable `output` will contain:

```yml
parent:
  - item1
  - item2
```