goldmark-gemtext: git.sr.ht/~kota/goldmark-gemtext Index | Examples | Files

package gemtext

import "git.sr.ht/~kota/goldmark-gemtext"

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

Examples

Package Files

block.go doc.go extra.go inline.go option.go render.go

Constants

const HR = ""

HR is the default HorizontalRule string used in NewConfig.

func New

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

New returns a gemtext renderer.

Example

Code:

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

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

RegisterFuncs implements NodeRenderer.RegisterFuncs.

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

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
)
Version
v0.3.2 (latest)
Published
Feb 20, 2022
Platform
linux/amd64
Imports
10 packages (graph)
Last checked
1 week ago

Tools for package owners.