markdown corpus · Jira convert · quality checks

canonic

canonical responses, versioned in git

Versioned canned-response corpus for Jira workflows - markdown under a shared configured prefix is the source of truth. Convert with pandoc, gate with quality checks, search and dedupe with Tantivy.

markdown corpus shared prefix pandoc → jira Tantivy BM25 review before migrate
Usage & CLI Design notes GitHub

Why canonic#

Shared support answers should live in git, not only in Jira comments. canonic treats version-controlled markdown under corpus/responses/ as the source of truth: check quality before migration, convert with pandoc’s Jira writer, lint with Vale or in-process Harper, and search or dedupe with a local Tantivy index.

Workflow at a glance#

  1. 1 Author in markdown Shared prefix from canonic.toml, front matter, team closing. {prefix}-*.md
  2. 2 Check quality Ids, prefix, sop, and generic closings - fail the PR early. canonic check
  3. 3 Search & dedupe Local Tantivy BM25 + Jaccard for near-copy discovery. canonic search · dedupe
  4. 4 Publish to Jira Convert or explicit one-shot comment; imports stay drafts until promote. canonic convert · jira-comment · tui
canonic architecture pipeline

Full pipeline diagram - details in Architecture.

What you need → what you run#

Validate before merge

Front matter, configured prefix id, and team closings.

  • canonic checkexit 1 on findings
Markdown → Jira wiki

Pandoc jira writer for a human to paste.

  • canonic convert PATH
Find similar answers

BM25 search and near-duplicate pairs.

  • canonic search "…"
  • canonic dedupe
Pull existing Jira text

REST read path → drafts under corpus/imports/.

  • canonic import-jira "JQL"

Install#

cargo install --git https://github.com/HaoZeke/canonic
# or from a checkout:
cargo build --release

Requirements: Rust 1.85+, pandoc for convert, optional Vale for style lint (Harper is linked in-process). Run canonic doctor to see what the environment can already do.

First canned response#

  1. Scaffold canonic new "Example topic" → corpus/responses/resp-example-topic.md (or edit the included demo resp-demo-shared-quota.md).
  2. Validate canonic check
  3. Index & search canonic reindex then canonic search "example topic"
  4. Convert Needs pandoc: canonic convert corpus/responses/resp-demo-shared-quota.md

Full command reference: Usage.

Documentation map#

Usage

CLI overview, corpus layout, dedupe, Jira import, exit codes.

Usage
Design

Why Tantivy, markdown-as-source, and the review-before-migrate rule.

Design notes
Architecture

Pipeline diagram, layers, and library module map.

Architecture
Rust API

Module map and embedded crate reference (sphinxcontrib-rust).

Rust API

Source & license#