Md (bushel.bushel.Bushel.Md)

Module Bushel.Md

Markdown processing with Bushel link extensions.

Bushel Markdown extensions and utilities

This module provides mappers to convert Bushel markdown extensions to different output formats. Bushel extends standard markdown with:

:slug - Links to bushel entries by slug

@@handle - Links to contacts by handle

##tag - Tag references

Two main mapper modes:

Sidenote mode for the main website (with previews)

Plain HTML mode for feeds and simple output

Sidenote Types

Sidenote data types for interactive previews on hover. These are defined here as Cmarkit inline extensions that can be generated by the sidenote mapper and rendered by the webserver.

type sidenote_data =

| Contact_note of Sortal_schema.Contact.t * string
| Paper_note of Bushel__.Bushel_paper.t * string
| Idea_note of Bushel__.Bushel_idea.t * string
| Note_note of Bushel__.Bushel_note.t * string
| Project_note of Bushel__.Bushel_project.t * string
| Video_note of Bushel__.Bushel_video.t * string
| Footnote_note of string * Cmarkit.Block.t * string

type Cmarkit.Inline.t +=

| Side_note of sidenote_data

Extensible inline for sidenotes

Link Detection

val is_bushel_slug : string -> bool

val is_tag_slug : string -> bool

val is_kind_slug : string -> bool

val is_contact_slug : string -> bool

val strip_handle : String.t -> String.t

Custom Link Resolution

val authorlink : unit Cmarkit.Meta.key

val sluglink : unit Cmarkit.Meta.key

val make_authorlink : Cmarkit.Label.t -> Cmarkit.Label.t

val make_sluglink : Cmarkit.Label.t -> Cmarkit.Label.t

val with_bushel_links : 
  [< `Def of Cmarkit.Label.t option * Cmarkit.Label.t
  | `Ref of 'a * Cmarkit.Label.t * Cmarkit.Label.t option ] ->
  Cmarkit.Label.t option

Custom label resolver for Bushel links

Text Extraction

val text_of_inline : Cmarkit.Inline.t -> string

Link Target Detection

val link_target_is_bushel : 
  ?slugs:(string, unit) Hashtbl.t ->
  Cmarkit.Inline.Link.t ->
  (string * string) option

val image_target_is_bushel : 
  Cmarkit.Inline.Link.t ->
  (string * Cmarkit.Block_line.tight list option * string) option

Plain Text Extraction

Strips bushel links from the AST and extracts plain text. Follows the same detection pattern as the sidenote and HTML mappers:

Inline-style links text(:slug) detected via link_target_is_bushel
Reference-style links text:slug detected via authorlink/sluglink metadata tags set by the resolver
:slug and ##tag links are deleted
@@handle links are replaced with the contact's full name
Images with bushel targets are deleted
Regular links and images are kept

val inline_to_plain_text : Cmarkit.Inline.t -> string

val make_plain_text_mapper : 
  ?contact_name:(String.t -> String.t option) ->
  unit ->
  Cmarkit.Mapper.t

val plain_text_of_markdown : 
  ?contact_name:(String.t -> String.t option) ->
  string ->
  string

Sidenote Mapper

Creates sidenotes for Bushel links. Used for interactive previews on the main website.

val resolve_link_text : Bushel__.Bushel_entry.t -> String.t -> String.t

Resolve link text: if it looks like a bushel slug, look up the entry title.

val make_sidenote_mapper : 
  Bushel__.Bushel_entry.t ->
  'a ->
  Cmarkit.Inline.t ->
  Cmarkit.Inline.t Cmarkit.Mapper.result

val make_bushel_inline_mapper : 
  Bushel__.Bushel_entry.t ->
  'a ->
  Cmarkit.Inline.t ->
  Cmarkit.Inline.t Cmarkit.Mapper.result

Alias for compatibility

Link-Only Mapper

Converts Bushel links to regular HTML links without sidenotes. Used for Atom feeds, RSS, search indexing.

val make_link_only_mapper : 
  Bushel__.Bushel_entry.t ->
  'a ->
  Cmarkit.Inline.t ->
  Cmarkit.Inline.t Cmarkit.Mapper.result

val make_bushel_link_only_mapper : 
  'a ->
  Bushel__.Bushel_entry.t ->
  'b ->
  Cmarkit.Inline.t ->
  Cmarkit.Inline.t Cmarkit.Mapper.result

Alias for compatibility

Slug Scanning

val scan_for_slugs : 'a -> string -> Cmarkit.Label.key list

Link Extraction

val extract_all_links : string -> String.t list

Extract all links from markdown text, including from images

val extract_external_links : string -> String.t list

Extract external URLs from markdown content

First Image Extraction

val extract_first_image : string -> string option

Plaintext Conversion

val markdown_to_plaintext : 'a -> string -> string

Convert markdown text to plain text, resolving bushel links to just their text

Validation

val make_validation_mapper : 
  Bushel__.Bushel_entry.t ->
  (Cmarkit.Label.key, unit) Hashtbl.t ->
  (Cmarkit.Label.key, unit) Hashtbl.t ->
  'a ->
  Cmarkit.Inline.t ->
  'b Cmarkit.Mapper.result

Validation mapper that collects broken references

val validate_references : 
  Bushel__.Bushel_entry.t ->
  string ->
  Cmarkit.Label.key list * Cmarkit.Label.key list

Validate all bushel references in markdown and return broken ones

Markdown to Markdown Conversion

val make_to_markdown_mapper : 
  ?base_url:string ->
  ?image_base:string ->
  Bushel__.Bushel_entry.t ->
  'a ->
  Cmarkit.Inline.t ->
  Cmarkit.Inline.t Cmarkit.Mapper.result

Create a mapper that converts Bushel markdown to standard markdown.

This resolves:

:slug links to Title(URL)
@@handle to Name(best_url)
##tag to tag(/tags/tag)
!:image-slug(caption) to !caption(/images/slug.webp)

val to_markdown : 
  ?base_url:string ->
  ?image_base:string ->
  entries:Bushel__.Bushel_entry.t ->
  string ->
  string

Convert Bushel markdown to standard markdown.

parameter base_url
Base URL prefix for entry links (default: "")

parameter image_base
Base path for images (default: "/images")

parameter entries
The entry collection for resolving links

parameter md
The Bushel-flavored markdown text

returns
Standard markdown with all Bushel extensions resolved

References

Reference extraction for CiTO annotations.

type reference_source =

| Paper
(*
CitesAsSourceDocument
*)
| Note
(*
CitesAsRelated
*)
| External
(*
Cites
*)

Reference source type for CiTO annotations

val note_references : 
  Bushel__.Bushel_entry.t ->
  Sortal_schema.Contact.t ->
  Bushel__.Bushel_note.t ->
  (string * string * reference_source) list

Extract references (papers/notes with DOIs) from a note. Returns a list of (doi, citation_text, reference_source) tuples.

parameter entries
The entry collection

parameter default_author
The default author contact for notes without explicit author

parameter note
The note to extract references from