gotextile

README

go-textile

A Go implementation of the Textile markup language with a stdlib-first parser and fixture-driven compatibility against the php-textile test suite. The renderer aims for parity with php-textile behavior without vendoring or invoking the PHP library.

Features

Block-level parsing

• Headings (h1.–h6.), paragraphs, and blockquotes.
• Code blocks (bc, pre) and extended block syntax (..).
• Lists (ordered/unordered), including nested and mixed list types.
• Tables with captions, colgroups, thead/tfoot/tbody sections, and cell alignment.
• Definition lists (classic and dash-style variants).
• Raw block handling for custom tags (optional).
• Block-level HTML wrapper detection and divider blocks (<br>, <hr>, <img>).

Inline parsing

• Emphasis, strong, bold/italic, insert/delete, sub/sup, cite, code spans.
• Links (inline, reference, quoted, bracketed) and images with attributes.
• Footnotes and notelists.
• Attribute fragments (class/id/style/lang/title) with normalization and ordering.
• Glyph substitutions (quotes, dashes, ellipses, trademarks, fractions, dimension “x”).
• Acronyms and caps wrapping.
• Bracketed phrases and fractions.

Modes and policies

• Restricted mode with HTML sanitization and scheme allowlisting.
• Lite mode for minimal Textile parsing.
• HTML5 vs. XHTML rendering (void tag style).
• Optional raw HTML block passthrough.
• URL sanitization/encoding helpers with prefix support.

Implementation status

• ✅ All vendored php-textile fixtures pass (go test ./...).
• ✅ Stdlib-first parsing with manual rune scanning (no regex-heavy parsing).
• ✅ Fixture-driven test harness with filtering/limiting support.

If new php-textile fixtures are added, run the full suite to confirm parity.

Usage

package main

import (
	"fmt"

	gotextile "github.com/rcarmo/go-textile"
)

func main() {
	input := "h1. Hello"
	html, err := gotextile.TextileToHtml(input)
	if err != nil {
		panic(err)
	}
	fmt.Println(html)
}

Options

type Options struct {
	Lite                bool
	Restricted          bool
	Images              bool
	DimensionlessImages bool
	LinkRelationship    string
	LinkPrefix          string
	ImagePrefix         string
	LineWrap            int
	RawBlocks           bool
	BlockTags           bool
	HTML5               bool
	NoGlyphs            bool
}

Use DefaultOptions() as a baseline and override as needed:

options := gotextile.DefaultOptions()
options.Restricted = true
options.HTML5 = true
html, err := gotextile.TextileToHtmlWithOptions(input, options)

Testing

The test suite is driven by vendored php-textile fixtures in test/fixtures.

# Run all fixtures

go test ./...

# Filter fixtures

TEXTILE_FIXTURE_FILTER="links.yaml" go test ./...

# Limit fixtures

TEXTILE_FIXTURE_LIMIT=50 go test ./...

Fixture provenance

See test/fixtures/README.md for the php-textile source/version details and included assets.

License

MIT — see LICENSE.

Documentation

Overview

Package gotextile provides a stdlib-first Textile parser with fixture-driven compatibility against php-textile.

The renderer supports block and inline Textile constructs (lists, tables, emphasis, links, images, glyph substitutions, footnotes, and more), along with restricted and lite modes. Use DefaultOptions as a baseline and override as needed.

Example:

input := "h1. Hello"
html, err := gotextile.TextileToHtml(input)
if err != nil {
	log.Fatal(err)
}
fmt.Println(html)

Index

• func TextileToHtml(text string) (string, error)
• func TextileToHtmlWithOptions(text string, options Options) (string, error)
• type Options
  • func DefaultOptions() Options

Examples

• TextileToHtml
• TextileToHtmlWithOptions

Functions

func TextileToHtml

func TextileToHtml(text string) (string, error)

TextileToHtml converts Textile markup to HTML using DefaultOptions.

Example

input := "h1. Hello"
output, _ := TextileToHtml(input)
fmt.Print(output)

Output:
<h1>Hello</h1>

func TextileToHtmlWithOptions

func TextileToHtmlWithOptions(text string, options Options) (string, error)

TextileToHtmlWithOptions converts Textile markup to HTML using the provided options.

The returned HTML includes a trailing newline to match the fixture suite output.

Example

options := DefaultOptions()
options.HTML5 = true
output, _ := TextileToHtmlWithOptions("p. Hi", options)
fmt.Print(output)

Output:
<p>Hi</p>

Types

type Options

type Options struct {
	// Lite disables most block-level parsing for a lighter-weight subset of Textile.
	Lite bool
	// Restricted sanitizes HTML and enforces scheme allowlists for links/images.
	Restricted bool
	// Images enables inline image handling (when false, images are left as text).
	Images bool
	// DimensionlessImages drops width/height attributes when true.
	DimensionlessImages bool
	// LinkRelationship sets the rel attribute on generated links (e.g., "nofollow").
	LinkRelationship string
	// LinkPrefix prepends a prefix to relative link URLs.
	LinkPrefix string
	// ImagePrefix prepends a prefix to relative image URLs.
	ImagePrefix string
	// LineWrap controls newline handling; 0 replaces newlines with spaces, -1 preserves them.
	LineWrap int
	// RawBlocks enables passthrough for raw block tags with custom namespaces.
	RawBlocks bool
	// BlockTags enables block-level HTML tag parsing/wrapping.
	BlockTags bool
	// HTML5 switches output to HTML5-style void tags and alignment classes.
	HTML5 bool
	// NoGlyphs disables glyph substitutions (e.g., smart quotes, ellipses).
	NoGlyphs bool
}

Options represents configuration switches for the Textile renderer. These map to the php-textile configuration used in the fixture suite.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the baseline php-textile-compatible defaults.