Crate mdq

This crate is the library behind the mdq CLI tool.

This is a preview API. While I’ll try to keep it as stable as possible, some breaking changes may occur.

I will note any such changes in the release notes on GitHub. You can also find them searching the breaking change label in the project’s issue tracker.

The general flow to use this crate is:

1. Parse Markdown into md_elem::MdElems via md_elem::MdDoc::parse
2. Parse a query via select::Selector’s TryFrom::<&str>
3. Use select::Selector::find_nodes to filter the MdElems down
4. Use output to write the results

The run module implements this workflow using options similar to the CLI’s flags and a facade for I/O. You can also do it yourself. See that module’s documentation for an example.

Example: End-to-end parsing and selection

To parse some Markdown and a query string and output the result as Markdown to stdout:

use indoc::indoc;

// Define some markdown
let markdown_text = indoc! {r##"
# First section

- hello
- world

# Second section

- foo
- bar
"##};
let parsed_md = mdq::md_elem::MdDoc::parse(markdown_text, &mdq::md_elem::ParseOptions::default())?;

// Parse a selector that looks for a section with title containing "second", and
// then looks for list items within it
let query_text = "# second | - *";
let selector: mdq::select::Selector = query_text.try_into()?;

// Run the selector against the parsed Markdown
let (found_nodes, found_nodes_ctx) = selector.find_nodes(parsed_md)?;

// Output. Note our use of
let mut output_string = String::new();
let writer = mdq::output::MdWriter::default();
writer.write(&found_nodes_ctx, &found_nodes, &mut output_string);

assert_eq!(
    output_string,
    indoc! {r"
    - foo

    - bar
"});

Modules

md_elem

Parsed Markdown nodes (and how to parse them).

output

Output md_elems to various formats.

run

End-to-end runs.

select

The query and filtering ability of mdq.