abbreviations

README

Goldmark Abbreviations Extension

A Goldmark extension that provides abbreviation handling mostly compatible with PHP Markdown Extra syntax. This extension converts abbreviation definitions into <abbr> HTML elements with proper title attributes.

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/Disable adding <abbr> tag to Headings
            abbreviations.WithAbbrEndnotesList(),  // Only one of these can be selected (List or Table)
            abbreviations.WithAbbrEndnotesTable(), // Only one of these can be selected (List or Table)
        ),
    ),
)

The default initialization when none of these options are specified:

• abbreviations.WithHeadingAbbr(false)
• No Endnotes -- neither Endnotes option is used

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

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>

Configuration Options

The extension supports several configuration options:

• WithHeadingAbbr(true) - Enable abbreviations in headings (disabled by default)
• WithAbbrEndnotesList() - Generate abbreviation list at document end
• WithAbbrEndnotesTable() - Generate abbreviation table at document end

Features

• Automatic text replacement with <abbr> tags
• Code blocks are excluded from processing
• Prevents nested abbreviation tags
• Unicode-aware text processing
• Integration with footnotes extension
• Invalid abbreviation definitions are handled gracefully

For more information, see: https://github.com/zmtcreative/gm-abbreviations

Index

• Variables
• func NewAbbreviations(opts ...AbbreviationsOption) *abbreviations
• type AbbreviationEndnotesList
  • func NewAbbreviationEndnotesList(abbreviations map[string]string) *AbbreviationEndnotesList
  • func (n *AbbreviationEndnotesList) Dump(source []byte, level int)
  • func (n *AbbreviationEndnotesList) Kind() ast.NodeKind
• type AbbreviationEndnotesTable
  • func NewAbbreviationEndnotesTable(abbreviations map[string]string) *AbbreviationEndnotesTable
  • func (n *AbbreviationEndnotesTable) Dump(source []byte, level int)
  • func (n *AbbreviationEndnotesTable) Kind() ast.NodeKind
• type AbbreviationsEndnotesType
• type AbbreviationsOption
  • func WithAbbrEndnotesList() AbbreviationsOption
  • func WithAbbrEndnotesTable() AbbreviationsOption
  • func WithHeadingAbbr(allow bool) AbbreviationsOption
• type InvalidAbbreviationDefinition
  • func NewInvalidAbbreviationDefinition(originalText string) *InvalidAbbreviationDefinition
  • func (n *InvalidAbbreviationDefinition) Dump(source []byte, level int)
  • func (n *InvalidAbbreviationDefinition) Kind() ast.NodeKind
• type InvalidAbbreviationList
  • func NewInvalidAbbreviationList() *InvalidAbbreviationList
  • func (n *InvalidAbbreviationList) Dump(source []byte, level int)
  • func (n *InvalidAbbreviationList) Kind() ast.NodeKind

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

var KindAbbreviationEndnotesList = ast.NewNodeKind("AbbreviationEndnotesList")

KindAbbreviationEndnotesList is the AST node kind for AbbreviationEndnotesList nodes. This can be used for AST traversal and node type checking.

var KindAbbreviationEndnotesTable = ast.NewNodeKind("AbbreviationEndnotesTable")

KindAbbreviationEndnotesTable is the AST node kind for AbbreviationEndnotesTable nodes. This can be used for AST traversal and node type checking.

var KindInvalidAbbreviationDefinition = ast.NewNodeKind("InvalidAbbreviationDefinition")

KindInvalidAbbreviationDefinition is the AST node kind for InvalidAbbreviationDefinition nodes. This can be used for AST traversal and node type checking.

var KindInvalidAbbreviationList = ast.NewNodeKind("InvalidAbbreviationList")

KindInvalidAbbreviationList is the AST node kind for InvalidAbbreviationList nodes. This can be used for AST traversal and node type checking.

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.

Example usage:

// Basic usage with default settings
ext := abbreviations.NewAbbreviations()

// With custom options
ext := abbreviations.NewAbbreviations(
    abbreviations.WithHeadingAbbr(true),
    abbreviations.WithAbbrEndnotesList(),
)

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

Types

type AbbreviationEndnotesList

type AbbreviationEndnotesList struct {
	ast.BaseBlock
	Abbreviations map[string]string
}

AbbreviationEndnotesList represents an abbreviation endnotes list in the AST. This node contains all abbreviations defined in the document and renders them as a bulleted list at the end of the document when WithAbbrEndnotesList() is used.

The list is inserted before footnotes if the footnotes extension is also enabled.

func NewAbbreviationEndnotesList

func NewAbbreviationEndnotesList(abbreviations map[string]string) *AbbreviationEndnotesList

NewAbbreviationEndnotesList creates a new AbbreviationEndnotesList node. The abbreviations parameter should contain a map of abbreviation names to their definitions.

This function is primarily used internally by the extension's transformer and should not typically be called by user code.

func (*AbbreviationEndnotesList) Dump

func (n *AbbreviationEndnotesList) Dump(source []byte, level int)

Dump implements ast.Node.Dump

func (*AbbreviationEndnotesList) Kind

func (n *AbbreviationEndnotesList) Kind() ast.NodeKind

Kind implements ast.Node.Kind

type AbbreviationEndnotesTable

type AbbreviationEndnotesTable struct {
	ast.BaseBlock
	Abbreviations map[string]string
}

AbbreviationEndnotesTable represents an abbreviation endnotes table in the AST. This node contains all abbreviations defined in the document and renders them as a table at the end of the document when WithAbbrEndnotesTable() is used.

The table is inserted before footnotes if the footnotes extension is also enabled.

func NewAbbreviationEndnotesTable

func NewAbbreviationEndnotesTable(abbreviations map[string]string) *AbbreviationEndnotesTable

NewAbbreviationEndnotesTable creates a new AbbreviationEndnotesTable node. The abbreviations parameter should contain a map of abbreviation names to their definitions.

This function is primarily used internally by the extension's transformer and should not typically be called by user code.

func (*AbbreviationEndnotesTable) Dump

func (n *AbbreviationEndnotesTable) Dump(source []byte, level int)

Dump implements ast.Node.Dump

func (*AbbreviationEndnotesTable) Kind

func (n *AbbreviationEndnotesTable) Kind() ast.NodeKind

Kind implements ast.Node.Kind

type AbbreviationsEndnotesType

type AbbreviationsEndnotesType int

AbbreviationsEndnotesType represents the type of endnotes to generate at the end of the document. This determines how abbreviations are displayed in the optional endnotes section.

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

	// EndnotesList generates abbreviations as a bulleted list at the document end.
	// Use WithAbbrEndnotesList() to enable this option.
	EndnotesList

	// EndnotesTable generates abbreviations as a table at the document end.
	// Use WithAbbrEndnotesTable() to enable this option.
	EndnotesTable
)

type AbbreviationsOption

type AbbreviationsOption func(*abbreviations)

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

func WithAbbrEndnotesList

func WithAbbrEndnotesList() AbbreviationsOption

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

The generated HTML structure will be:

<div class="abbreviations abbr-list">
    <p class="abbr-title">Abbreviations</p>
    <ul>
        <li><strong>HTML</strong>: HyperText Markup Language</li>
        <li><strong>CSS</strong>: Cascading Style Sheets</li>
    </ul>
</div>

func WithAbbrEndnotesTable

func WithAbbrEndnotesTable() AbbreviationsOption

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

The generated HTML structure will be:

<div class="abbreviations abbr-table">
    <p class="abbr-title">Abbreviations</p>
    <table>
        <thead>
            <tr><th>Abbreviation</th><th>Definition</th></tr>
        </thead>
        <tbody>
            <tr><td>HTML</td><td>HyperText Markup Language</td></tr>
            <tr><td>CSS</td><td>Cascading Style Sheets</td></tr>
        </tbody>
    </table>
</div>

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

Setting allow to true enables abbreviation processing in headings:

ext := abbreviations.NewAbbreviations(
    abbreviations.WithHeadingAbbr(true),
)

type InvalidAbbreviationDefinition

type InvalidAbbreviationDefinition struct {
	ast.BaseBlock
	OriginalText string
}

InvalidAbbreviationDefinition represents an invalid abbreviation definition in the AST. This node is created when an abbreviation definition doesn't meet validation criteria, such as starting with invalid characters or containing prohibited symbols.

Invalid definitions are rendered as a list item with CSS class "abbr-invalid" to help users identify problematic abbreviation definitions in their documents.

func NewInvalidAbbreviationDefinition

func NewInvalidAbbreviationDefinition(originalText string) *InvalidAbbreviationDefinition

NewInvalidAbbreviationDefinition creates a new InvalidAbbreviationDefinition node. The originalText parameter should contain the full original abbreviation definition line.

This function is primarily used internally by the extension's parser and should not typically be called by user code.

func (*InvalidAbbreviationDefinition) Dump

func (n *InvalidAbbreviationDefinition) Dump(source []byte, level int)

Dump implements ast.Node.Dump

func (*InvalidAbbreviationDefinition) Kind

func (n *InvalidAbbreviationDefinition) Kind() ast.NodeKind

Kind implements ast.Node.Kind

type InvalidAbbreviationList

type InvalidAbbreviationList struct {
	ast.BaseBlock
}

InvalidAbbreviationList represents a container for multiple invalid abbreviation definitions in the AST. This node groups consecutive invalid abbreviation definitions together and renders them as a bulleted list with appropriate CSS styling and error indicators.

func NewInvalidAbbreviationList

func NewInvalidAbbreviationList() *InvalidAbbreviationList

NewInvalidAbbreviationList creates a new InvalidAbbreviationList node.

This function is primarily used internally by the extension's transformer and should not typically be called by user code.

func (*InvalidAbbreviationList) Dump

func (n *InvalidAbbreviationList) Dump(source []byte, level int)

Dump implements ast.Node.Dump

func (*InvalidAbbreviationList) Kind

func (n *InvalidAbbreviationList) Kind() ast.NodeKind

Kind implements ast.Node.Kind