format

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 15, 2022 License: MIT Imports: 7 Imported by: 2

README

format

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.

Index

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 (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
}

type GitHubFlavoredMarkdown

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 (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 (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

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AzureDevOpsMarkdown

type AzureDevOpsMarkdown struct{}

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

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 (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

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
}

Format is a generic interface for formatting documentation contents in a particular way.

type GitHubFlavoredMarkdown

type GitHubFlavoredMarkdown struct{}

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/

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 (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

type PlainMarkdown struct{}

PlainMarkdown provides a Format which is compatible with the base Markdown format specification.

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 (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.

Directories

Path Synopsis
Package formatcore provides utilities for creating formatters like those found in the format package.
Package formatcore provides utilities for creating formatters like those found in the format package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL