github.com/phsym/gomarkdoc@v0.5.4/format/format.go (about)

     1  package format
     2  
     3  import "github.com/phsym/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  	// Header converts the provided text into a header of the provided level.
    16  	// The level is expected to be at least 1.
    17  	Header(level int, text string) (string, error)
    18  
    19  	// RawHeader converts the provided text into a header of the provided level
    20  	// without escaping the header text. The level is expected to be at least 1.
    21  	RawHeader(level int, text string) (string, error)
    22  
    23  	// LocalHref generates an href for navigating to a header with the given
    24  	// headerText located within the same document as the href itself.
    25  	LocalHref(headerText string) (string, error)
    26  
    27  	// Link generates a link with the given text and href values.
    28  	Link(text, href string) (string, error)
    29  
    30  	// CodeHref generates an href to the provided code entry.
    31  	CodeHref(loc lang.Location) (string, error)
    32  
    33  	// ListEntry generates an unordered list entry with the provided text at the
    34  	// provided zero-indexed depth. A depth of 0 is considered the topmost level
    35  	// of list.
    36  	ListEntry(depth int, text string) (string, error)
    37  
    38  	// Accordion generates a collapsible content. The accordion's visible title
    39  	// while collapsed is the provided title and the expanded content is the
    40  	// body.
    41  	Accordion(title, body string) (string, error)
    42  
    43  	// AccordionHeader generates the header visible when an accordion is
    44  	// collapsed.
    45  	//
    46  	// The AccordionHeader is expected to be used in conjunction with
    47  	// AccordionTerminator() when the demands of the body's rendering requires
    48  	// it to be generated independently. The result looks conceptually like the
    49  	// following:
    50  	//
    51  	//	accordion := formatter.AccordionHeader("Accordion Title") + "Accordion Body" + formatter.AccordionTerminator()
    52  	AccordionHeader(title string) (string, error)
    53  
    54  	// AccordionTerminator generates the code necessary to terminate an
    55  	// accordion after the body. It is expected to be used in conjunction with
    56  	// AccordionHeader(). See AccordionHeader for a full description.
    57  	AccordionTerminator() (string, error)
    58  
    59  	// Paragraph formats a paragraph with the provided text as the contents.
    60  	Paragraph(text string) (string, error)
    61  
    62  	// Escape escapes special markdown characters from the provided text.
    63  	Escape(text string) string
    64  }