abbreviations

README

Goldmark Abbreviations Extension

This is a Goldmark extension that provides abbreviation handling mostly compatible with PHP Markdown Extra syntax when configured with its default values. This extension converts abbreviation definitions into <abbr> HTML elements using the title attribute.

Installation

go get github.com/zmtcreative/gm-abbreviations

Quick Start

Basic Usage

package main

import (
    "fmt"
    "github.com/yuin/goldmark"
    "github.com/zmtcreative/gm-abbreviations"
)

func main() {
    md := goldmark.New(
        goldmark.WithExtensions(
            abbreviations.NewAbbreviations(),
        ),
    )

    source := `## This is HTML

This is a basic description of HTML. It often uses CSS for styling.
Use CSS to make your HTML look pretty.

*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets`

    var buf bytes.Buffer
    if err := md.Convert([]byte(source), &buf); err != nil {
        panic(err)
    }
    fmt.Print(buf.String())
}

Output:

<h2>This is HTML</h2>
<p>This is a basic description of <abbr title="HyperText Markup Language">HTML</abbr>.
It often uses <abbr title="Cascading Style Sheets">CSS</abbr> for styling.
Use <abbr title="Cascading Style Sheets">CSS</abbr> to make your
<abbr title="HyperText Markup Language">HTML</abbr> look pretty.</p>

Advanced Options

You can combine multiple configuration options:

md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(
            abbreviations.WithHeadingAbbr(true),         // Enable abbreviations in headings
            abbreviations.WithShowInvalidNames(true),    // Show invalid abbreviation names as lists
            abbreviations.WithMaximumMatches(2),         // Limit to 2 matches per abbreviation
            abbreviations.WithEndnotesList(),            // Generate list endnotes with default title
            abbreviations.WithEndnotesTable("Acronyms"), // Generate table endnotes with custom title
            abbreviations.WithEndnotesGlossary(),        // Generate glossary endnotes with default title
        ),
    ),
)

Maximum Matches Control

By default, every occurrence of an abbreviation in the text will be converted to an <abbr> tag. You can limit this behavior:

// Only convert the first occurrence of each abbreviation
md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(
            abbreviations.WithMaximumMatches(1),
        ),
    ),
)

// Disable all abbreviation conversion (definitions still processed for endnotes)
md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(
            abbreviations.WithMaximumMatches(0),
        ),
    ),
)

With WithMaximumMatches(2) and the text "HTML is great and HTML is useful for web HTML development", only the first two instances of "HTML" would be converted to <abbr> tags, leaving the third instance as plain text.

Symbol Management

By default, abbreviation names can contain letters, numbers, spaces, and these symbols: -, _, ., +, /, :, ;, &, #, '. You can customize which symbols are allowed:

// Use only specific symbols
md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(
            abbreviations.WithAllowedSymbols([]rune{'-', '_', '@'}),
        ),
    ),
)

// Add additional symbols to the defaults
md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(
            abbreviations.WithAdditionalAllowedSymbols([]rune{'@', '!'}),
        ),
    ),
)

// Remove specific symbols from the defaults
md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(
            abbreviations.WithoutAllowedSymbols([]rune{'#', '&'}),
        ),
    ),
)

You can also manage symbols after creating the extension:

ext := abbreviations.NewAbbreviations()

// Set completely new allowed symbols
ext.SetAllowedSymbols([]rune{'-', '_', '.'})

// Add a symbol
ext.AddAllowedSymbol('@')

// Remove a symbol
ext.RemoveAllowedSymbol('#')

md := goldmark.New(goldmark.WithExtensions(ext))

Option Functions:

• WithHeadingAbbr(bool) - Enable or disable abbreviations in headings (default: false)
• WithShowInvalidNames(bool) - Show invalid abbreviation names as HTML lists or HTML comments (default: false)
• WithMaximumMatches(int) - Limit the number of times each abbreviation will be matched and converted (default: unlimited)
• WithEndnotesList(title...) - Generate list endnotes (defaults to "Abbreviations")
• WithEndnotesTable(title...) - Generate table endnotes (defaults to "Abbreviations")
• WithEndnotesGlossary(title...) - Generate glossary endnotes (defaults to "Glossary")
• WithAllowedSymbols([]rune) - Set custom allowed symbols for abbreviation names
• WithAdditionalAllowedSymbols([]rune) - Add symbols to the default allowed symbols
• WithoutAllowedSymbols([]rune) - Remove specific symbols from the default allowed symbols

Each endnotes function accepts an optional title parameter. If no title is provided, the default is used.

The default initialization when none of these options are specified:

• abbreviations.WithHeadingAbbr(false) - Abbreviations disabled in headings
• abbreviations.WithShowInvalidNames(false) - Invalid abbreviation names rendered as HTML comments
• No Endnotes -- none of the endnote options are used

For more detailed information, see the FEATURES.md document.

Performance

[!IMPORTANT]

There are performance impacts to consider when using this extension. See FEATURES:Performance for more information.

The extension's performance should be acceptable for all but the largest markdown documents and/or documents using significant numbers of abbreviations.

License

MIT License - see LICENSE.md for details.

Related Projects

• Goldmark - The extensible Markdown parser this extension is built for
• PHP Markdown Extra - The original specification this extension implements

Documentation

Overview

Package abbreviations provides a Goldmark extension for handling abbreviations in Markdown documents, similar to PHP Markdown Extra's abbreviation syntax.

This extension allows you to define abbreviations using the syntax:

*[ABBR]: Definition text

And automatically converts abbreviation occurrences in the text to HTML <abbr> tags with appropriate title attributes.

Basic Usage

md := goldmark.New(
    goldmark.WithExtensions(
        abbreviations.NewAbbreviations(),
    ),
)

source := `This is HTML.

*[HTML]: HyperText Markup Language`

// Converts to: <p>This is <abbr title="HyperText Markup Language">HTML</abbr>.</p>

For comprehensive documentation, configuration options, and advanced usage examples, see FEATURES.md in the project repository.

Index

• Constants
• Variables
• func NewAbbreviations(opts ...AbbreviationsOption) *abbreviations
• type AbbreviationsEndnotesType
• type AbbreviationsOption
  • func WithAdditionalAllowedSymbols(symbols []rune) AbbreviationsOption
  • func WithAllowedSymbols(symbols []rune) AbbreviationsOption
  • func WithEndnotesGlossary(title ...string) AbbreviationsOption
  • func WithEndnotesList(title ...string) AbbreviationsOption
  • func WithEndnotesTable(title ...string) AbbreviationsOption
  • func WithHeadingAbbr(allow bool) AbbreviationsOption
  • func WithHeadingAbbreviations(allow bool) AbbreviationsOption
  • func WithMaximumMatches(maximumMatches int) AbbreviationsOption
  • func WithShowInvalidNames(show bool) AbbreviationsOption
  • func WithoutAllowedSymbols(symbols []rune) AbbreviationsOption

Constants

const (
	// EndnotesNone means no endnotes will be generated (default behavior).
	// Abbreviations will only appear as <abbr> tags in the text.
	EndnotesNone = config.EndnotesNone

	// EndnotesList generates abbreviations as a bulleted list at the document end.
	// Use WithEndnotesList() or WithEndnotesListTitle() to enable this option.
	EndnotesList = config.EndnotesList

	// EndnotesTable generates abbreviations as a table at the document end.
	// Use WithEndnotesTable() or WithEndnotesTableTitle() to enable this option.
	EndnotesTable = config.EndnotesTable

	// EndnotesGlossary generates abbreviations as a definition list at the document end.
	// Use WithEndnotesGlossary() or WithEndnotesGlossaryTitle() to enable this option.
	EndnotesGlossary = config.EndnotesGlossary
)

Variables

var Abbreviations = NewAbbreviations()

Abbreviations is a default instance of the abbreviations extension with default settings. This provides an alternative way to initialize the extension:

goldmark.WithExtensions(abbreviations.Abbreviations)

The preferred method is still using the constructor:

goldmark.WithExtensions(abbreviations.NewAbbreviations())

Functions

func NewAbbreviations

func NewAbbreviations(opts ...AbbreviationsOption) *abbreviations

NewAbbreviations creates a new abbreviations extension with the given options. By default, abbreviations are disabled in headings and no endnotes are generated. For configuration options and usage examples, see FEATURES.md.

Types

type AbbreviationsEndnotesType

type AbbreviationsEndnotesType = config.AbbreviationsEndnotesType

Re-export public types from internal packages

type AbbreviationsOption

type AbbreviationsOption func(*config.Abbreviations)

AbbreviationsOption is a functional option for configuring the abbreviations extension. Options are applied when creating a new extension instance with NewAbbreviations.

func WithAdditionalAllowedSymbols

func WithAdditionalAllowedSymbols(symbols []rune) AbbreviationsOption

WithAdditionalAllowedSymbols adds additional symbols to the default allowed symbols. This extends the default set rather than replacing it. For detailed usage and examples, see FEATURES.md.

func WithAllowedSymbols

func WithAllowedSymbols(symbols []rune) AbbreviationsOption

WithAllowedSymbols sets the allowed symbols for abbreviation names. This replaces the default allowed symbols with the provided list. For detailed usage and examples, see FEATURES.md.

func WithEndnotesGlossary

func WithEndnotesGlossary(title ...string) AbbreviationsOption

WithEndnotesGlossary enables abbreviations to be listed as a definition list at the end of the document. The glossary will be inserted before footnotes if the footnotes extension is also used. If no title is provided, defaults to "Glossary". Only the first title parameter is used. For detailed usage and examples, see FEATURES.md.

func WithEndnotesList

func WithEndnotesList(title ...string) AbbreviationsOption

WithEndnotesList enables abbreviations to be listed as a bulleted list at the end of the document. The list will be inserted before footnotes if the footnotes extension is also used. If no title is provided, defaults to "Abbreviations". Only the first title parameter is used. For detailed usage and examples, see FEATURES.md.

func WithEndnotesTable

func WithEndnotesTable(title ...string) AbbreviationsOption

WithEndnotesTable enables abbreviations to be listed as a table at the end of the document. The table will be inserted before footnotes if the footnotes extension is also used. If no title is provided, defaults to "Abbreviations". Only the first title parameter is used. For detailed usage and examples, see FEATURES.md.

func WithHeadingAbbr

func WithHeadingAbbr(allow bool) AbbreviationsOption

WithHeadingAbbr sets whether abbreviations should be applied in headings. By default, abbreviations are not processed in headings (h1-h6 tags). For detailed usage and examples, see FEATURES.md.

func WithHeadingAbbreviations

func WithHeadingAbbreviations(allow bool) AbbreviationsOption

WithHeadingAbbreviations sets whether abbreviations should be applied in headings. This is an alternative name for WithHeadingAbbr.

func WithMaximumMatches

func WithMaximumMatches(maximumMatches int) AbbreviationsOption

WithMaximumMatches enables limiting the number of times each abbreviation will be matched and converted. By default, abbreviations are unlimited and every occurrence is converted. Setting maximumMatches to 0 disables all abbreviation conversion while still processing definitions. For detailed usage and examples, see FEATURES.md.

func WithShowInvalidNames

func WithShowInvalidNames(show bool) AbbreviationsOption

WithShowInvalidNames sets whether invalid abbreviation names should be rendered as HTML lists. By default, invalid abbreviation names are not displayed (showInvalidNames = false). When enabled, invalid definitions are rendered as bulleted lists with CSS class "abbr-invalid". For detailed usage and examples, see FEATURES.md.

func WithoutAllowedSymbols

func WithoutAllowedSymbols(symbols []rune) AbbreviationsOption

WithoutAllowedSymbols removes specific symbols from the allowed symbols. This allows removing default symbols that you don't want to allow. For detailed usage and examples, see FEATURES.md.