package omd

  1. Overview
  2. Docs

Module OmdSource

A markdown parser in OCaml, with no extra dependencies.

This module represents this entire Markdown library written in OCaml only.

Its main purpose is to allow you to use the Markdown library while keeping you away from the other modules.

If you want to extend the Markdown parser, you can do it without accessing any module of this library but this one, and by doing so, you are free from having to maintain a fork of this library.

N.B. This module is supposed to be reentrant, if it's not then please report the bug.

Representation of Markdown documents

Sourcetype t = element list

Representation of a Markdown document.

Sourceand ref_container = < add_ref : string -> string -> string -> unit ; get_ref : string -> (string * string) option ; get_all : (string * (string * string)) list >
Sourceand element = Omd_representation.element =
  1. | H1 of t
    (*

    Header of level 1

    *)
  2. | H2 of t
    (*

    Header of level 2

    *)
  3. | H3 of t
    (*

    Header of level 3

    *)
  4. | H4 of t
    (*

    Header of level 4

    *)
  5. | H5 of t
    (*

    Header of level 5

    *)
  6. | H6 of t
    (*

    Header of level 6

    *)
  7. | Paragraph of t
    (*

    A Markdown paragraph (must be enabled in of_string)

    *)
  8. | Text of string
    (*

    Text.

    *)
  9. | Emph of t
    (*

    Emphasis (italic)

    *)
  10. | Bold of t
    (*

    Bold

    *)
  11. | Ul of t list
    (*

    Unumbered list

    *)
  12. | Ol of t list
    (*

    Ordered (i.e. numbered) list

    *)
  13. | Ulp of t list
  14. | Olp of t list
  15. | Code of name * string
    (*

    Code(lang, code) represent code within the text (Markdown: `code`). The language lang cannot be specified from Markdown, it can be from of_string though or when programatically generating Markdown documents. Beware that the code is taken verbatim from Markdown and may contain characters that must be escaped for HTML.

    *)
  16. | Code_block of name * string
    (*

    Code_block(lang, code): a code clock (e.g. indented by 4 spaces in the text). The first parameter lang is the language if specified. Beware that the code is taken verbatim from Markdown and may contain characters that must be escaped for HTML.

    *)
  17. | Br
    (*

    (Forced) line break

    *)
  18. | Hr
    (*

    Horizontal rule

    *)
  19. | NL
    (*

    Newline character. Newline characters that act like delimiters (e.g. for paragraphs) are removed from the AST.

    *)
  20. | Url of href * t * title
  21. | Ref of ref_container * name * string * fallback
  22. | Img_ref of ref_container * name * alt * fallback
  23. | Html of name * (string * string option) list * t
  24. | Html_block of name * (string * string option) list * t
  25. | Html_comment of string
    (*

    An HTML comment, including "<!--" and "-->".

    *)
  26. | Raw of string
    (*

    Raw: something that shall never be converted

    *)
  27. | Raw_block of string
    (*

    Raw_block: a block with contents that shall never be converted

    *)
  28. | Blockquote of t
    (*

    Quoted block

    *)
  29. | Img of alt * src * title
  30. | X of < name : string ; to_html : ?indent:int -> (t -> string) -> t -> string option ; to_sexpr : (t -> string) -> t -> string option ; to_t : t -> t option >

A element of a Markdown document.

Sourceand fallback = < to_string : string ; to_t : t >

Fallback for references in case they refer to non-existant references

Sourceand name = string

Markdown reference name.

Sourceand alt = string

HTML img tag attribute.

Sourceand src = string

HTML attribute.

Sourceand href = string

HTML attribute.

Sourceand title = string

HTML attribute.

Sourcetype code_stylist = lang:string -> string -> string

Function that takes a language name and some code and returns that code with style.

Input and Output

Sourceval of_string : ?extensions:Omd_representation.extensions -> ?default_lang:name -> string -> t

of_string s returns the Markdown representation of the string s.

  • parameter lang

    language for blocks of code where it was not specified. Default: "".

If you want to use a custom lexer or parser, use Omd_lexer.lex and Omd_parser.parse.

Sourceval of_bigarray : ?extensions:Omd_representation.extensions -> ?default_lang:name -> Omd_lexer.bigstring -> t

As of_string, but read input from a bigarray rather than from a string.

Sourceval set_default_lang : name -> t -> t

set_default_lang lang md return a copy of md where the language of all Code or Code_block with an empty language is set to lang.

Sourceval to_html : ?override:(Omd_representation.element -> string option) -> ?pindent:bool -> ?nl2br:bool -> ?cs:code_stylist -> t -> string

Translate markdown representation into raw HTML. If you need a full HTML representation, you mainly have to figure out how to convert Html of string and Html_block of string into your HTML representation.

Sourceval to_markdown : t -> string

Translate markdown representation into textual markdown.

Sourceval to_text : t -> string

Translate markdown representation into raw text.

Tansforming Markdown documents

Sourceval toc : ?start:int list -> ?depth:int -> t -> t

toc md returns toc a table of contents for md.

  • parameter start

    gives the section for which the TOC must be built. For example ~start:[2;3] will build the TOC for subsections of the second H1 header, and within that section, the third h2 header. If a number is 0, it means to look for the first section at that level but stop if one encounters any other subsection. If no subsection exists, an empty TOC [] will be returned. Default: [] i.e. list all sections, starting with the first H1.

  • parameter depth

    the table of contents. Default: 2.