markdown

Documentation

Overview

Package markdown renders the given goldmark AST to Markdown.

Index

• Variables
• type CodeFormatter
• type ListIndentStyle
• type Option
  • func WithCodeFormatters(fs ...CodeFormatter) Option
  • func WithEmphasisToken(c rune) Option
  • func WithListIndentStyle(style ListIndentStyle) Option
  • func WithSoftWraps() Option
  • func WithStrongToken(s string) Option
  • func WithUnderlineHeadings() Option
• type Renderer
  • func NewRenderer() *Renderer
  • func (mr *Renderer) AddMarkdownOptions(opts ...Option)
  • func (mr *Renderer) AddOptions(opts ...renderer.Option)
  • func (mr *Renderer) Render(w io.Writer, source []byte, node ast.Node) error

Variables

var GoCodeFormatter = CodeFormatter{
	Name:    "go",
	Aliases: []string{"Go"},
	Format:  formatGo,
}

GoCodeFormatter is a CodeFormatter that reformats Go source code inside fenced code blocks tagged with 'go' or 'Go'.

```go
func main() {
}
```

Supply it to the renderer with WithCodeFormatters.

Types

type CodeFormatter

type CodeFormatter struct {
	// Name of the language.
	Name string

	// Aliases for the language, if any.
	Aliases []string

	// Function to format the code snippet.
	// In case of errors, format functions should typically return
	// the original string unchanged.
	Format func([]byte) []byte
}

CodeFormatter reformats code samples found in the document, matching them by name.

type ListIndentStyle

type ListIndentStyle int

ListIndentStyle specifies how items nested inside lists should be indented.

const (
	// ListIndentAligned specifies that items inside a list item
	// should be aligned to the content in the first item.
	//
	//	- First paragraph.
	//
	//	  Second paragraph aligned with the first.
	//
	// This applies to ordered lists too.
	//
	//	1. First paragraph.
	//
	//	   Second paragraph aligned with the first.
	//
	//	...
	//
	//	10. Contents.
	//
	//	    Long lists indent content further.
	//
	// This is the default.
	ListIndentAligned ListIndentStyle = iota

	// ListIndentUniform specifies that items inside a list item
	// should be aligned uniformly with 4 spaces.
	//
	// For example:
	//
	//	- First paragraph.
	//
	//	    Second paragraph indented 4 spaces.
	//
	// For ordered lists:
	//
	//	1. First paragraph.
	//
	//	    Second paragraph indented 4 spaces.
	//
	//	...
	//
	//	10. Contents.
	//
	//	    Always indented 4 spaces.
	ListIndentUniform
)

type Option

type Option interface {
	renderer.Option
	// contains filtered or unexported methods
}

Option customizes the behavior of the markdown renderer.

func WithCodeFormatters

func WithCodeFormatters(fs ...CodeFormatter) Option

WithCodeFormatters changes the functions used to reformat code blocks found in the original file.

formatters := []markdown.CodeFormatter{
	markdown.GoCodeFormatter,
	// ...
}
r := NewRenderer()
r.AddMarkdownOptions(WithCodeFormatters(formatters...))

Defaults to empty.

func WithEmphasisToken

func WithEmphasisToken(c rune) Option

WithEmphasisToken specifies the character used to wrap emphasised text. Per the CommonMark spec, valid values are '*' and '_'.

Defaults to '*'.

func WithListIndentStyle

func WithListIndentStyle(style ListIndentStyle) Option

WithListIndentStyle specifies how contents nested under a list item should be indented.

Defaults to ListIndentAligned.

func WithSoftWraps

func WithSoftWraps() Option

WithSoftWraps allows you to wrap lines even on soft line breaks.

func WithStrongToken

func WithStrongToken(s string) Option

WithStrongToken specifies the string used to wrap bold text. Per the CommonMark spec, valid values are '**' and '__'.

Defaults to repeating the emphasis token twice. See WithEmphasisToken for how to change that.

func WithUnderlineHeadings

func WithUnderlineHeadings() Option

WithUnderlineHeadings configures the renderer to use Setext-style headers (=== and ---).

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

Renderer allows to render markdown AST into markdown bytes in consistent format. Render is reusable across Renders, it holds configuration only.

func NewRenderer

func NewRenderer() *Renderer

NewRenderer builds a new Markdown renderer with default settings. To use this with goldmark.Markdown, use the goldmark.WithRenderer option.

r := markdown.NewRenderer()
md := goldmark.New(goldmark.WithRenderer(r))
md.Convert(src, w)

Alternatively, you can call Renderer.Render directly.

r := markdown.NewRenderer()
r.Render(w, src, node)

Use Renderer.AddMarkdownOptions to customize the output of the renderer.

func (*Renderer) AddMarkdownOptions

func (mr *Renderer) AddMarkdownOptions(opts ...Option)

AddMarkdownOptions modifies the Renderer with the given options.

func (*Renderer) AddOptions

func (mr *Renderer) AddOptions(opts ...renderer.Option)

AddOptions pulls Markdown renderer specific options from the given list, and applies them to the renderer.

func (*Renderer) Render

func (mr *Renderer) Render(w io.Writer, source []byte, node ast.Node) error

Render renders the given AST node to the given writer, given the original source from which the node was parsed.

NOTE: This is the entry point used by Goldmark.