import "github.com/princjef/gomarkdoc/format"
Package format defines output formats for emitting documentation information.
Each of the formats in this package contains the same set of formatting functions, but not all formats support all of the functions natively. Where possible, a fallback format is provided. See the documentation for the individual formats for more information.
- type AzureDevOpsMarkdown
- func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error)
- func (f *AzureDevOpsMarkdown) AccordionHeader(title string) (string, error)
- func (f *AzureDevOpsMarkdown) AccordionTerminator() (string, error)
- func (f *AzureDevOpsMarkdown) Bold(text string) (string, error)
- func (f *AzureDevOpsMarkdown) CodeBlock(language, code string) (string, error)
- func (f *AzureDevOpsMarkdown) CodeHref(loc lang.Location) (string, error)
- func (f *AzureDevOpsMarkdown) Escape(text string) string
- func (f *AzureDevOpsMarkdown) Header(level int, text string) (string, error)
- func (f *AzureDevOpsMarkdown) Link(text, href string) (string, error)
- func (f *AzureDevOpsMarkdown) ListEntry(depth int, text string) (string, error)
- func (f *AzureDevOpsMarkdown) LocalHref(headerText string) (string, error)
- func (f *AzureDevOpsMarkdown) Paragraph(text string) (string, error)
- func (f *AzureDevOpsMarkdown) RawHeader(level int, text string) (string, error)
- type Format
- type GitHubFlavoredMarkdown
- func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error)
- func (f *GitHubFlavoredMarkdown) AccordionHeader(title string) (string, error)
- func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error)
- func (f *GitHubFlavoredMarkdown) Bold(text string) (string, error)
- func (f *GitHubFlavoredMarkdown) CodeBlock(language, code string) (string, error)
- func (f *GitHubFlavoredMarkdown) CodeHref(loc lang.Location) (string, error)
- func (f *GitHubFlavoredMarkdown) Escape(text string) string
- func (f *GitHubFlavoredMarkdown) Header(level int, text string) (string, error)
- func (f *GitHubFlavoredMarkdown) Link(text, href string) (string, error)
- func (f *GitHubFlavoredMarkdown) ListEntry(depth int, text string) (string, error)
- func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error)
- func (f *GitHubFlavoredMarkdown) Paragraph(text string) (string, error)
- func (f *GitHubFlavoredMarkdown) RawHeader(level int, text string) (string, error)
- type PlainMarkdown
- func (f *PlainMarkdown) Accordion(title, body string) (string, error)
- func (f *PlainMarkdown) AccordionHeader(title string) (string, error)
- func (f *PlainMarkdown) AccordionTerminator() (string, error)
- func (f *PlainMarkdown) Bold(text string) (string, error)
- func (f *PlainMarkdown) CodeBlock(language, code string) (string, error)
- func (f *PlainMarkdown) CodeHref(loc lang.Location) (string, error)
- func (f *PlainMarkdown) Escape(text string) string
- func (f *PlainMarkdown) Header(level int, text string) (string, error)
- func (f *PlainMarkdown) Link(text, href string) (string, error)
- func (f *PlainMarkdown) ListEntry(depth int, text string) (string, error)
- func (f *PlainMarkdown) LocalHref(headerText string) (string, error)
- func (f *PlainMarkdown) Paragraph(text string) (string, error)
- func (f *PlainMarkdown) RawHeader(level int, text string) (string, error)
type AzureDevOpsMarkdown
AzureDevOpsMarkdown provides a Format which is compatible with Azure DevOps's syntax and semantics. See the Azure DevOps documentation for more details about their markdown format: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops
type AzureDevOpsMarkdown struct{}
func (*AzureDevOpsMarkdown) Accordion
func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error)
Accordion generates a collapsible content. The accordion's visible title while collapsed is the provided title and the expanded content is the body.
func (*AzureDevOpsMarkdown) AccordionHeader
func (f *AzureDevOpsMarkdown) AccordionHeader(title string) (string, error)
AccordionHeader generates the header visible when an accordion is collapsed.
The AccordionHeader is expected to be used in conjunction with AccordionTerminator() when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following:
accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator()
func (*AzureDevOpsMarkdown) AccordionTerminator
func (f *AzureDevOpsMarkdown) AccordionTerminator() (string, error)
AccordionTerminator generates the code necessary to terminate an accordion after the body. It is expected to be used in conjunction with AccordionHeader(). See AccordionHeader for a full description.
func (*AzureDevOpsMarkdown) Bold
func (f *AzureDevOpsMarkdown) Bold(text string) (string, error)
Bold converts the provided text to bold
func (*AzureDevOpsMarkdown) CodeBlock
func (f *AzureDevOpsMarkdown) CodeBlock(language, code string) (string, error)
CodeBlock wraps the provided code as a code block and tags it with the provided language (or no language if the empty string is provided).
func (*AzureDevOpsMarkdown) CodeHref
func (f *AzureDevOpsMarkdown) CodeHref(loc lang.Location) (string, error)
CodeHref generates an href to the provided code entry.
func (*AzureDevOpsMarkdown) Escape
func (f *AzureDevOpsMarkdown) Escape(text string) string
Escape escapes special markdown characters from the provided text.
func (*AzureDevOpsMarkdown) Header
func (f *AzureDevOpsMarkdown) Header(level int, text string) (string, error)
Header converts the provided text into a header of the provided level. The level is expected to be at least 1.
func (*AzureDevOpsMarkdown) Link
func (f *AzureDevOpsMarkdown) Link(text, href string) (string, error)
Link generates a link with the given text and href values.
func (*AzureDevOpsMarkdown) ListEntry
func (f *AzureDevOpsMarkdown) ListEntry(depth int, text string) (string, error)
ListEntry generates an unordered list entry with the provided text at the provided zero-indexed depth. A depth of 0 is considered the topmost level of list.
func (*AzureDevOpsMarkdown) LocalHref
func (f *AzureDevOpsMarkdown) LocalHref(headerText string) (string, error)
LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself. Link generation follows the guidelines here: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops#anchor-links
func (*AzureDevOpsMarkdown) Paragraph
func (f *AzureDevOpsMarkdown) Paragraph(text string) (string, error)
Paragraph formats a paragraph with the provided text as the contents.
func (*AzureDevOpsMarkdown) RawHeader
func (f *AzureDevOpsMarkdown) RawHeader(level int, text string) (string, error)
RawHeader converts the provided text into a header of the provided level without escaping the header text. The level is expected to be at least 1.
type Format
Format is a generic interface for formatting documentation contents in a particular way.
type Format interface {
// Bold converts the provided text to bold
Bold(text string) (string, error)
// CodeBlock wraps the provided code as a code block and tags it with the
// provided language (or no language if the empty string is provided).
CodeBlock(language, code string) (string, error)
// Header converts the provided text into a header of the provided level.
// The level is expected to be at least 1.
Header(level int, text string) (string, error)
// RawHeader converts the provided text into a header of the provided level
// without escaping the header text. The level is expected to be at least 1.
RawHeader(level int, text string) (string, error)
// LocalHref generates an href for navigating to a header with the given
// headerText located within the same document as the href itself.
LocalHref(headerText string) (string, error)
// Link generates a link with the given text and href values.
Link(text, href string) (string, error)
// CodeHref generates an href to the provided code entry.
CodeHref(loc lang.Location) (string, error)
// ListEntry generates an unordered list entry with the provided text at the
// provided zero-indexed depth. A depth of 0 is considered the topmost level
// of list.
ListEntry(depth int, text string) (string, error)
// Accordion generates a collapsible content. The accordion's visible title
// while collapsed is the provided title and the expanded content is the
// body.
Accordion(title, body string) (string, error)
// AccordionHeader generates the header visible when an accordion is
// collapsed.
//
// The AccordionHeader is expected to be used in conjunction with
// AccordionTerminator() when the demands of the body's rendering requires
// it to be generated independently. The result looks conceptually like the
// following:
//
// accordion := formatter.AccordionHeader("Accordion Title") + "Accordion Body" + formatter.AccordionTerminator()
AccordionHeader(title string) (string, error)
// AccordionTerminator generates the code necessary to terminate an
// accordion after the body. It is expected to be used in conjunction with
// AccordionHeader(). See AccordionHeader for a full description.
AccordionTerminator() (string, error)
// Paragraph formats a paragraph with the provided text as the contents.
Paragraph(text string) (string, error)
// Escape escapes special markdown characters from the provided text.
Escape(text string) string
}
GitHubFlavoredMarkdown provides a Format which is compatible with GitHub Flavored Markdown's syntax and semantics. See GitHub's documentation for more details about their markdown format: https://guides.github.com/features/mastering-markdown/
type GitHubFlavoredMarkdown struct{}
func (*GitHubFlavoredMarkdown) Accordion
func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error)
Accordion generates a collapsible content. The accordion's visible title while collapsed is the provided title and the expanded content is the body.
func (*GitHubFlavoredMarkdown) AccordionHeader
func (f *GitHubFlavoredMarkdown) AccordionHeader(title string) (string, error)
AccordionHeader generates the header visible when an accordion is collapsed.
The AccordionHeader is expected to be used in conjunction with AccordionTerminator() when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following:
accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator()
func (*GitHubFlavoredMarkdown) AccordionTerminator
func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error)
AccordionTerminator generates the code necessary to terminate an accordion after the body. It is expected to be used in conjunction with AccordionHeader(). See AccordionHeader for a full description.
func (*GitHubFlavoredMarkdown) Bold
func (f *GitHubFlavoredMarkdown) Bold(text string) (string, error)
Bold converts the provided text to bold
func (*GitHubFlavoredMarkdown) CodeBlock
func (f *GitHubFlavoredMarkdown) CodeBlock(language, code string) (string, error)
CodeBlock wraps the provided code as a code block and tags it with the provided language (or no language if the empty string is provided).
func (*GitHubFlavoredMarkdown) CodeHref
func (f *GitHubFlavoredMarkdown) CodeHref(loc lang.Location) (string, error)
CodeHref generates an href to the provided code entry.
func (*GitHubFlavoredMarkdown) Escape
func (f *GitHubFlavoredMarkdown) Escape(text string) string
Escape escapes special markdown characters from the provided text.
func (*GitHubFlavoredMarkdown) Header
func (f *GitHubFlavoredMarkdown) Header(level int, text string) (string, error)
Header converts the provided text into a header of the provided level. The level is expected to be at least 1.
func (*GitHubFlavoredMarkdown) Link
func (f *GitHubFlavoredMarkdown) Link(text, href string) (string, error)
Link generates a link with the given text and href values.
func (*GitHubFlavoredMarkdown) ListEntry
func (f *GitHubFlavoredMarkdown) ListEntry(depth int, text string) (string, error)
ListEntry generates an unordered list entry with the provided text at the provided zero-indexed depth. A depth of 0 is considered the topmost level of list.
func (*GitHubFlavoredMarkdown) LocalHref
func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error)
LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself.
func (*GitHubFlavoredMarkdown) Paragraph
func (f *GitHubFlavoredMarkdown) Paragraph(text string) (string, error)
Paragraph formats a paragraph with the provided text as the contents.
func (*GitHubFlavoredMarkdown) RawHeader
func (f *GitHubFlavoredMarkdown) RawHeader(level int, text string) (string, error)
RawHeader converts the provided text into a header of the provided level without escaping the header text. The level is expected to be at least 1.
type PlainMarkdown
PlainMarkdown provides a Format which is compatible with the base Markdown format specification.
type PlainMarkdown struct{}
func (*PlainMarkdown) Accordion
func (f *PlainMarkdown) Accordion(title, body string) (string, error)
Accordion generates a collapsible content. Since accordions are not supported by plain markdown, this generates a level 6 header followed by a paragraph.
func (*PlainMarkdown) AccordionHeader
func (f *PlainMarkdown) AccordionHeader(title string) (string, error)
AccordionHeader generates the header visible when an accordion is collapsed. Since accordions are not supported in plain markdown, this generates a level 6 header.
The AccordionHeader is expected to be used in conjunction with AccordionTerminator() when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following:
accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator()
func (*PlainMarkdown) AccordionTerminator
func (f *PlainMarkdown) AccordionTerminator() (string, error)
AccordionTerminator generates the code necessary to terminate an accordion after the body. Since accordions are not supported in plain markdown, this completes a paragraph section. It is expected to be used in conjunction with AccordionHeader(). See AccordionHeader for a full description.
func (*PlainMarkdown) Bold
func (f *PlainMarkdown) Bold(text string) (string, error)
Bold converts the provided text to bold
func (*PlainMarkdown) CodeBlock
func (f *PlainMarkdown) CodeBlock(language, code string) (string, error)
CodeBlock wraps the provided code as a code block. The provided language is ignored as it is not supported in plain markdown.
func (*PlainMarkdown) CodeHref
func (f *PlainMarkdown) CodeHref(loc lang.Location) (string, error)
CodeHref always returns the empty string, as there is no defined file linking format in standard markdown.
func (*PlainMarkdown) Escape
func (f *PlainMarkdown) Escape(text string) string
Escape escapes special markdown characters from the provided text.
func (*PlainMarkdown) Header
func (f *PlainMarkdown) Header(level int, text string) (string, error)
Header converts the provided text into a header of the provided level. The level is expected to be at least 1.
func (*PlainMarkdown) Link
func (f *PlainMarkdown) Link(text, href string) (string, error)
Link generates a link with the given text and href values.
func (*PlainMarkdown) ListEntry
func (f *PlainMarkdown) ListEntry(depth int, text string) (string, error)
ListEntry generates an unordered list entry with the provided text at the provided zero-indexed depth. A depth of 0 is considered the topmost level of list.
func (*PlainMarkdown) LocalHref
func (f *PlainMarkdown) LocalHref(headerText string) (string, error)
LocalHref always returns the empty string, as header links are not supported in plain markdown.
func (*PlainMarkdown) Paragraph
func (f *PlainMarkdown) Paragraph(text string) (string, error)
Paragraph formats a paragraph with the provided text as the contents.
func (*PlainMarkdown) RawHeader
func (f *PlainMarkdown) RawHeader(level int, text string) (string, error)
RawHeader converts the provided text into a header of the provided level without escaping the header text. The level is expected to be at least 1.
Generated by gomarkdoc