github.com/dkischenko/gomarkdoc@v0.0.0-20230516135336-e40deae8a495/format/format.go (about)

     1  package format
     2  
     3  import "github.com/dkischenko/gomarkdoc/lang"
     4  
     5  // Format is a generic interface for formatting documentation contents in a
     6  // particular way.
     7  type Format interface {
     8  	// Bold converts the provided text to bold
     9  	Bold(text string) (string, error)
    10  
    11  	// CodeBlock wraps the provided code as a code block and tags it with the
    12  	// provided language (or no language if the empty string is provided).
    13  	CodeBlock(language, code string) (string, error)
    14  
    15  	// Anchor produces an anchor for the provided link.
    16  	Anchor(anchor string) string
    17  
    18  	// AnchorHeader converts the provided text and custom anchor link into a
    19  	// header of the provided level. The level is expected to be at least 1.
    20  	AnchorHeader(level int, text, anchor string) (string, error)
    21  
    22  	// Header converts the provided text into a header of the provided level.
    23  	// The level is expected to be at least 1.
    24  	Header(level int, text string) (string, error)
    25  
    26  	// RawAnchorHeader converts the provided text and custom anchor link into a
    27  	// header of the provided level without escaping the header text. The level
    28  	// is expected to be at least 1.
    29  	RawAnchorHeader(level int, text, anchor string) (string, error)
    30  
    31  	// RawHeader converts the provided text into a header of the provided level
    32  	// without escaping the header text. The level is expected to be at least 1.
    33  	RawHeader(level int, text string) (string, error)
    34  
    35  	// LocalHref generates an href for navigating to a header with the given
    36  	// headerText located within the same document as the href itself.
    37  	LocalHref(headerText string) (string, error)
    38  
    39  	// RawLocalHref generates an href within the same document but with a direct
    40  	// link provided instead of text to slugify.
    41  	RawLocalHref(anchor string) string
    42  
    43  	// Link generates a link with the given text and href values.
    44  	Link(text, href string) (string, error)
    45  
    46  	// CodeHref generates an href to the provided code entry.
    47  	CodeHref(loc lang.Location) (string, error)
    48  
    49  	// ListEntry generates an unordered list entry with the provided text at the
    50  	// provided zero-indexed depth. A depth of 0 is considered the topmost level
    51  	// of list.
    52  	ListEntry(depth int, text string) (string, error)
    53  
    54  	// Accordion generates a collapsible content. The accordion's visible title
    55  	// while collapsed is the provided title and the expanded content is the
    56  	// body.
    57  	Accordion(title, body string) (string, error)
    58  
    59  	// AccordionHeader generates the header visible when an accordion is
    60  	// collapsed.
    61  	//
    62  	// The AccordionHeader is expected to be used in conjunction with
    63  	// AccordionTerminator() when the demands of the body's rendering requires
    64  	// it to be generated independently. The result looks conceptually like the
    65  	// following:
    66  	//
    67  	//	accordion := formatter.AccordionHeader("Accordion Title") + "Accordion Body" + formatter.AccordionTerminator()
    68  	AccordionHeader(title string) (string, error)
    69  
    70  	// AccordionTerminator generates the code necessary to terminate an
    71  	// accordion after the body. It is expected to be used in conjunction with
    72  	// AccordionHeader(). See AccordionHeader for a full description.
    73  	AccordionTerminator() (string, error)
    74  
    75  	// Escape escapes special markdown characters from the provided text.
    76  	Escape(text string) string
    77  }