gemtext

README

goldmark-gemtext

A gemtext renderer for goldmark. You can use this library to parse commonmark markdown (with support for autolinks and strikethrough) and convert it into nice clean looking gemtext (with some options). This library does the heavy lifting for gemgen.

Several markdown extensions are supported and can be enabled as goldmark parser extensions. The following are currently supported: extension.Linkify, extension.Strikethrough, and wiki.Wiki.

You create a renderer with New(option...) and pass in options:

var src = `
# This is a heading

This is a [paragraph](https://en.wikipedia.org/wiki/Paragraph) with [some
links](https://en.wikipedia.org/wiki/Hyperlink) in it.

Next we'll have a list of some musicians I like, but as an individual list of
links. One of the neat features of goldmark-gemtext is that it recognizes when
a "paragraph" is really just a list of links and handles it as if it's a list
of links by simply converting them to the gemtext format. I wasn't able to find
any other markdown to gemtext tools that could do this so it was the
inspiration for writing this in the first place.

[Noname](https://nonameraps.bandcamp.com/)\
[Milo](https://afrolab9000.bandcamp.com/album/so-the-flies-dont-come)\
[Busdriver](https://busdriver-thumbs.bandcamp.com/)\
[Neat Beats](https://www.youtube.com/watch?v=X6kGg31G0As)\
[Ratatat](http://www.ratatatmusic.com/)\
[Sylvan Esso](https://www.sylvanesso.com/)\
[Phoebe Bridgers](https://phoebefuckingbridgers.com/)
`

// create markdown parser
var buf bytes.Buffer
md := goldmark.New(
  goldmark.WithExtensions(
    extension.Linkify,
    extension.Strikethrough,
  ),
)

// set some options
var options = []Option{WithHeadingLink(HeadingLinkAuto), WithCodeSpan(CodeSpanMarkdown)}

md.SetRenderer(New(options...))
_ = md.Convert([]byte(src), &buf) // ignoring errors for example
fmt.Println(buf.String())

There's a bunch of options. You can read them in the documentaton. If you have suggestions, issues, or anything else drop an email in the mailing list.

Documentation

Overview

Package gemtext provides a gemtext Renderer for use with the goldmark library: https://github.com/yuin/goldmark

Gemtext is a lightweight markup language for use over the Gemini protocol, it's more or less a subset of Markdown so by definition some source material MUST be lost during a proper conversion. This library offers several configuration options for different ways of handling this simplification. You can learn more about Genini here: https://gemini.circumlunar.space/

Index

• Constants
• func New(opts ...Option) renderer.Renderer
• type CodeSpan
• type Config
  • func NewConfig() *Config
• type Emphasis
• type GemRenderer
  • func NewGemRenderer(config *Config) *GemRenderer
  • func (r *GemRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)
• type HeadingLink
• type HeadingSpace
• type LinkReplacer
• type LinkType
• type Option
  • func WithCodeSpan(val CodeSpan) Option
  • func WithConfig(config *Config) Option
  • func WithEmphasis(val Emphasis) Option
  • func WithHeadingLink(val HeadingLink) Option
  • func WithHeadingSpace(val HeadingSpace) Option
  • func WithHorizontalRule(val string) Option
  • func WithLinkReplacers(r []LinkReplacer) Option
  • func WithParagraphLink(val ParagraphLink) Option
  • func WithStrikethrough(val Strikethrough) Option
• type OptionFunc
  • func (o OptionFunc) SetConfig(c *Config)
• type ParagraphLink
• type Strikethrough

Examples

• New

Constants

const HR = ""

HR is the default HorizontalRule string used in NewConfig.

Functions

func New

func New(opts ...Option) renderer.Renderer

New returns a gemtext renderer.

Example

src := `
# This is a heading

This is a [paragraph](https://en.wikipedia.org/wiki/Paragraph) with [some
links](https://en.wikipedia.org/wiki/Hyperlink) in it.

Next we'll have a list of some musicians I like, but as an individual list of
links. One of the neat features of goldmark-gemtext is that it recognizes when
a "paragraph" is really just a list of links and handles it as if it's a list
of links by simply converting them to the gemtext format. I wasn't able to find
any other markdown to gemtext tools that could do this so it was the
inspiration for writing this in the first place.

[Noname](https://nonameraps.bandcamp.com/)\
[Milo](https://afrolab9000.bandcamp.com/album/so-the-flies-dont-come)\
[Busdriver](https://busdriver-thumbs.bandcamp.com/)\
[Neat Beats](https://www.youtube.com/watch?v=X6kGg31G0As)\
[Ratatat](http://www.ratatatmusic.com/)\
[Sylvan Esso](https://www.sylvanesso.com/)\
[Phoebe Bridgers](https://phoebefuckingbridgers.com/)
`
// create markdown parser
var buf bytes.Buffer
md := goldmark.New(
	goldmark.WithExtensions(
		extension.Linkify,
		extension.Strikethrough,
	),
)

// set some options
options := []Option{WithHeadingLink(HeadingLinkAuto), WithCodeSpan(CodeSpanMarkdown)}

md.SetRenderer(New(options...))
_ = md.Convert([]byte(src), &buf) // ignoring errors for example
fmt.Println(buf.String())

Output:

# This is a heading

This is a paragraph with some links in it.

=> https://en.wikipedia.org/wiki/Paragraph paragraph
=> https://en.wikipedia.org/wiki/Hyperlink some links

Next we'll have a list of some musicians I like, but as an individual list of links. One of the neat features of goldmark-gemtext is that it recognizes when a "paragraph" is really just a list of links and handles it as if it's a list of links by simply converting them to the gemtext format. I wasn't able to find any other markdown to gemtext tools that could do this so it was the inspiration for writing this in the first place.

=> https://nonameraps.bandcamp.com/ Noname
=> https://afrolab9000.bandcamp.com/album/so-the-flies-dont-come Milo
=> https://busdriver-thumbs.bandcamp.com/ Busdriver
=> https://www.youtube.com/watch?v=X6kGg31G0As Neat Beats
=> http://www.ratatatmusic.com/ Ratatat
=> https://www.sylvanesso.com/ Sylvan Esso
=> https://phoebefuckingbridgers.com/ Phoebe Bridgers

Types

type CodeSpan

type CodeSpan uint8

CodeSpan is an enum config option that controls how markdown codespan is treated.

const (
	// Strip out markdown codespan symbols.
	CodeSpanOff CodeSpan = iota
	// Print markdown codespan symbols.
	CodeSpanMarkdown
)

type Config

type Config struct {
	HeadingLink    HeadingLink
	HeadingSpace   HeadingSpace
	ParagraphLink  ParagraphLink
	Emphasis       Emphasis
	Strikethrough  Strikethrough
	CodeSpan       CodeSpan
	HorizontalRule string
	LinkReplacers  []LinkReplacer
}

Config has configurations for the gemini renderer.

func NewConfig

func NewConfig() *Config

NewConfig returns a new Config with defaults.

type Emphasis

type Emphasis uint8

Emphasis is an enum config option that controls how markdown emphasis (bold and italics) are treated.

const (
	// Strip out markdown emphasis symbols (* and _)
	EmphasisOff Emphasis = iota
	// Print markdown emphasis symbols for italics and bold (** and _)
	EmphasisMarkdown
	// Print markdown emphasis using 𝘄𝗲𝗶𝗿𝗱 𝘶𝘯𝘪𝘤𝘰𝘥𝘦 hacks.
	// NOTE: The current generation of screenreaders are unable to handle this
	// hack. The symbols are meant for mathematics and are pronounced
	// individually as such. As a result you should ONLY use this option if
	// you're providing an alternative accessible copy of your document.
	EmphasisUnicode
)

type GemRenderer

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

A GemRenderer struct is an implementation of renderer.GemRenderer that renders nodes as gemtext.

func NewGemRenderer

func NewGemRenderer(config *Config) *GemRenderer

NewGemRenderer returns a new renderer.NodeRenderer.

func (*GemRenderer) RegisterFuncs

func (r *GemRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs implements NodeRenderer.RegisterFuncs.

type HeadingLink

type HeadingLink uint8

HeadingLink is an emun config option that controls how links in headings are treated.

const (
	// Ignore links in headings; writing the label of the link in its place.
	HeadingLinkOff HeadingLink = iota
	// If the heading contains only links, use the first link instead of
	// printing a heading. Otherwise print a heading, ignoring links.
	HeadingLinkAuto
	// Print all links below heading.
	HeadingLinkBelow
)

type HeadingSpace

type HeadingSpace uint8

HeadingSpace is an emun config option that controls how many newline characters are entered after a heading.

const (
	// Enter just a single newline after the heading. Content will be smacked
	// up right below it.
	HeadingSpaceSingle HeadingSpace = iota
	// Enter two newlines below the heading. Giving content some nice breathing
	// room.
	HeadingSpaceDouble
)

type LinkReplacer

type LinkReplacer struct {
	Type        LinkType
	Regex       *regexp.Regexp
	Replacement string
}

LinkReplacer is used to modify links with regular expressions. This could be used to change links that end in .md to .gmi.

type LinkType

type LinkType uint8

LinkType is an enum describing a type of markdown link. A LinkReplacer can be applied to one or multiple link types. This makes it easy to have a regular expression only apply to wiki style links, but ignore traditional markdown links and auto links for example.

const (
	// LinkMarkdown is a traditional markdown link using brackets and
	// parenthesis.
	LinkMarkdown LinkType = iota
	// LinkAuto is a markdown link that was automatically detected with
	// heuristics. This type of link must be supported by your goldmark parser
	// to be used. There's an official extension that adds it.
	LinkAuto
	// LinkWiki is a wiki style link. This is a non-standard, but popular syntax
	// used in some wiki's that would otherwise be compliant markdown. I wrote a
	// goldmark extension to detect this type of link:
	// https://git.sr.ht/~kota/goldmark-wiki
	LinkWiki
	// LinkImage is a markdown image link.
	LinkImage
)

type Option

type Option interface {
	// Replace the current configuration.
	SetConfig(*Config)
}

An Option interface sets options for gemini renderers.

func WithCodeSpan

func WithCodeSpan(val CodeSpan) Option

Set CodeSpan mode.

func WithConfig

func WithConfig(config *Config) Option

Pass a completely new config as an option.

func WithEmphasis

func WithEmphasis(val Emphasis) Option

Set Emphasis mode.

func WithHeadingLink

func WithHeadingLink(val HeadingLink) Option

Set HeadingLink mode.

func WithHeadingSpace

func WithHeadingSpace(val HeadingSpace) Option

Set HeadingSpace mode.

func WithHorizontalRule

func WithHorizontalRule(val string) Option

Set HorizontalRule string.

func WithLinkReplacers

func WithLinkReplacers(r []LinkReplacer) Option

Set LinkReplacers.

func WithParagraphLink

func WithParagraphLink(val ParagraphLink) Option

Set ParagraphLink mode.

func WithStrikethrough

func WithStrikethrough(val Strikethrough) Option

Set Strikethrough mode.

type OptionFunc

type OptionFunc func(*Config)

A function that implements the Option interface.

func (OptionFunc) SetConfig

func (o OptionFunc) SetConfig(c *Config)

SetConfig replaces the current configuration.

type ParagraphLink

type ParagraphLink uint8

ParagraphLink is an enum config option that controls how links in paragraphs are treated.

const (
	// Ignore links in paragraphs; writing the label of the link in its place.
	ParagraphLinkOff ParagraphLink = iota
	// Print links below paragraph.
	ParagraphLinkBelow
	// Delimit link text with curly braces and print the below the paragraph.
	ParagraphLinkCurlyBelow
)

type Strikethrough

type Strikethrough uint8

Strikethrough is an enum config option that controls how markdown strikethrough (per the github markdown extension) is treated.

const (
	// Strip out markdown strikethrough symbols (~~).
	StrikethroughOff Strikethrough = iota
	// Print markdown strikethrough symbols (~~).
	StrikethroughMarkdown
	// Print strikethrough using 𝘄𝗲𝗶𝗿𝗱 𝘶𝘯𝘪𝘤𝘰𝘥𝘦 hacks.
	// NOTE: The current generation of screenreaders are unable to handle this
	// hack. The symbols are generated by manipulating diacritical marks which
	// traditionally influence pronunciation. As a result you should ONLY use
	// this option if you're providing an alternative accessible copy of your
	// document.
	StrikethroughUnicode
)