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:

gleam add --dev checkmark simplifile envoy

Update a markdown file:

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:

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.