✨ Initial implementation

Author: chrisjsewell

.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    commit-message:
+      prefix: ⬆️
+    schedule:
+      interval: weekly
+  - package-ecosystem: cargo
+    directory: /
+    commit-message:
+      prefix: ⬆️
+    schedule:
+      interval: weekly

.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - uses: pre-commit/[email protected]
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: cargo build --verbose
+    - name: Run tests
+      run: cargo test --verbose

.gitignore

@@ -12,3 +12,9 @@ Cargo.lock
 
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
+
+
+# Added by cargo
+
+/target
+/Cargo.lock

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+
+- repo: local
+  hooks:
+  - id: fmt
+    name: fmt
+    description: Format files with cargo fmt.
+    entry: cargo fmt
+    language: rust
+    types: [rust]
+    args: ["--"]

Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "markdown-it-front-matter"
+version = "0.1.0"
+authors = ["Chris Sewell <[email protected]>"]
+description = "A markdown-it plugin for parsing front matter"
+readme = "README.md"
+repository = "https://github.com/chrisjsewell/markdown-it-front-matter.rs"
+keywords = ["markdown", "markdown-it"]
+categories = ["text-processing", "parsing"]
+license = "Apache-2.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+markdown-it = "0.5.0"
+
+[dev-dependencies]
+indoc = "2.0.1"
+rstest = "0.17.0"

README.md

@@ -1,2 +1,47 @@
 # markdown-it-front-matter.rs
- A markdown-it.rs plugin to process front matter containers
+
+A [markdown-it.rs](https://crates.io/crates/markdown-it) plugin to process front matter containers.
+
+## Usage
+
+```rust
+let parser = &mut markdown_it::MarkdownIt::new();
+markdown_it_front_matter::add(parser);
+let ast  = parser.parse("---\nfoo: bar\n---\n");
+
+print!("{:#?}", ast.children);
+// [
+//     Node {
+//         children: [],
+//         srcmap: Some(
+//             (
+//                 0,
+//                 16,
+//             ),
+//         ),
+//         ext: NodeExtSet(
+//             {},
+//         ),
+//         attrs: [],
+//         node_type: markdown_it_front_matter::FrontMatter,
+//         node_value: FrontMatter {
+//             content: "foo: bar\n",
+//         },
+//     },
+// ]
+```
+
+## Valid Front Matter
+
+Essentially, valid front matter is a fenced block:
+
+* Indicated by **three** or **more** dashes: `---`
+* Opening and closing fences must be the same number of *dash* characters
+* Opening fence must begin on the first line of the markdown string/file
+* Opening fence must not be indented
+
+```yaml
+---
+valid-front-matter: true
+---
+```

src/lib.rs

@@ -0,0 +1,93 @@
+//! A [markdown_it] plugin for parsing front matter
+//!
+//! ```
+//! let parser = &mut markdown_it::MarkdownIt::new();
+//! markdown_it_front_matter::add(parser);
+//! let node  = parser.parse("---\nfoo: bar\n---\n");
+//! ```
+
+use markdown_it::parser::block::{BlockRule, BlockState};
+use markdown_it::parser::core::Root;
+use markdown_it::{MarkdownIt, Node, NodeValue, Renderer};
+
+#[derive(Debug)]
+/// AST node for front-matter
+pub struct FrontMatter {
+    pub content: String,
+}
+
+impl NodeValue for FrontMatter {
+    fn render(&self, _node: &Node, _fmt: &mut dyn Renderer) {
+        // simply bypass the front-matter in HTML output
+    }
+}
+
+/// Add the front-matter extension to the markdown parser
+pub fn add(md: &mut MarkdownIt) {
+    // insert this rule into block subparser
+    md.block.add_rule::<FrontMatterBlockScanner>().before_all();
+}
+
+/// An extension for the block subparser.
+struct FrontMatterBlockScanner;
+
+impl BlockRule for FrontMatterBlockScanner {
+    fn run(state: &mut BlockState) -> Option<(Node, usize)> {
+        // check the parent is the document Root
+        if !state.node.is::<Root>() {
+            return None;
+        }
+
+        // check we are on the first line of the document
+        if state.line != 0 {
+            return None;
+        }
+
+        // check line starts with opening dashes
+        let opening = state
+            .get_line(state.line)
+            .chars()
+            .take_while(|c| *c == '-')
+            .collect::<String>();
+        if !opening.starts_with("---") {
+            return None;
+        }
+
+        // Search for the end of the block
+        let mut next_line = state.line;
+        loop {
+            next_line += 1;
+            if next_line >= state.line_max {
+                return None;
+            }
+
+            let line = state.get_line(next_line);
+            if line.starts_with(&opening) {
+                break;
+            }
+        }
+
+        // get the content of the block
+        let (content, _) = state.get_lines(state.line + 1, next_line, 0, true);
+
+        // return new node and number of lines it occupies
+        Some((Node::new(FrontMatter { content }), next_line + 1))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_works() {
+        let parser = &mut markdown_it::MarkdownIt::new();
+        add(parser);
+        let node = parser.parse("---\nfoo: bar\n---\nhallo\n");
+        // println!("{:#?}", ast.children.first());
+        assert!(node.children.first().unwrap().is::<FrontMatter>());
+
+        let text = node.render();
+        assert_eq!(text, "hallo\n")
+    }
+}

tests/fixtures.md

@@ -0,0 +1,87 @@
+
+should parse empty front matter:
+.
+---
+---
+# Head
+.
+
+<h1>Head</h1>
+.
+
+
+should parse basic front matter:
+.
+---
+x: 1
+---
+# Head
+.
+
+<h1>Head</h1>
+.
+
+should parse until triple dots:
+.
+---
+x: 1
+...
+# Head
+.
+
+<h1>Head</h1>
+.
+
+should parse front matter with indentation:
+.
+---
+title: Associative arrays
+people:
+    name: John Smith
+    age: 33
+morePeople: { name: Grace Jones, age: 21 }
+---
+# Head
+.
+
+<h1>Head</h1>
+.
+
+should ignore spaces after front matter delimiters:
+.
+---
+title: Associative arrays
+people:
+    name: John Smith
+    age: 33
+morePeople: { name: Grace Jones, age: 21 }
+---
+# Head
+.
+
+<h1>Head</h1>
+.
+
+should ignore front matter with less than 3 opening dashes:
+.
+--
+x: 1
+--
+# Head
+.
+<h2>--
+x: 1</h2>
+<h1>Head</h1>
+.
+
+should require front matter have matching number of opening and closing dashes:
+.
+----
+x: 1
+---
+# Head
+.
+<hr>
+<h2>x: 1</h2>
+<h1>Head</h1>
+.