checkmark

Checkmark helps you keep your markdown code snippets up to date! You can either check that snippets match sources, or automatically update them.

A source (of truth) can be one of the following:

• An entire file (any language)
• A full Gleam function definition
• A Gleam function body
• A Gleam type definition

A target to check or update can be:

• A code snippet in a markdown file
• A markdown code snippet in a Gleam comment

All types of sources and targets can be freely mixed and matched.

Examples

Add the dependencies required by the example:

sh deps gleam add --dev checkmark simplifile envoy

Update a markdown file:

gleam markdown import checkmark import envoy import simplifile pub fn example_test() { let checker = checkmark.new(simplifile.read, simplifile.write) let assert Ok(snippets) = checkmark.load_snippet_source(checker, "./test/doc_snippets_test.gleam") assert checker |> checkmark.document("README.md") |> checkmark.should_contain_contents_of("./example.sh", tagged: "sh deps") |> checkmark.should_contain_contents_of( "./test/example_test.gleam", tagged: "gleam markdown", ) |> checkmark.should_contain_snippet_from( snippets, checkmark.FunctionBody("update_docs_test"), tagged: "update comments", ) // Update locally, check on CI |> checkmark.check_or_update( when: envoy.get("GITHUB_WORKFLOW") == Error(Nil), ) == Ok(Nil) }

Update comments in code:

gleam update comments let checker = checkmark.new(simplifile.read, simplifile.write) let assert Ok(snippets) = checkmark.load_snippet_source(checker, "./test/doc_snippets_test.gleam") assert checker |> checkmark.comments_in("./src/checkmark.gleam") |> checkmark.should_contain_snippet_from( snippets, checkmark.FunctionBody("contents_of_example"), tagged: "contents_of", ) |> checkmark.should_contain_snippet_from( snippets, checkmark.FunctionBody("snippet_from_example"), tagged: "snippet_from", ) // Update locally, check on CI |> checkmark.check_or_update( when: envoy.get("GITHUB_WORKFLOW") == Error(Nil), ) == Ok(Nil)

These examples are, in fact, kept up to date and checked using checkmark!

Further documentation can be found at https://hexdocs.pm/checkmark.