Documentation
¶
Overview ¶
Package richtext provides utilities for converting between Markdown and HTML. It uses glamour for terminal-friendly Markdown rendering.
Index ¶
- Variables
- func AttachmentToHTML(sgid, filename, contentType string) string
- func DetectMIME(path string) string
- func EmbedAttachments(html string, attachments []AttachmentRef) string
- func HTMLToMarkdown(html string) string
- func Hyperlink(text, url string) string
- func IsHTML(s string) bool
- func IsMarkdown(s string) bool
- func LinkifyMarkdownLinks(text string) string
- func LinkifyURLs(text string) string
- func MarkdownToHTML(md string) string
- func MentionToHTML(sgid, name string) string
- func NormalizeDragPath(raw string) string
- func RenderMarkdown(md string) (string, error)
- func RenderMarkdownWithWidth(md string, width int) (string, error)
- func ValidateFile(path string) error
- type AttachmentRef
- type MentionLookupFunc
- type MentionResult
- type ParsedAttachment
- type PersonByIDFunc
Constants ¶
This section is empty.
Variables ¶
var ErrMentionSkip = errors.New("mention skip")
ErrMentionSkip is a sentinel error that lookup functions can return to indicate that a fuzzy @Name mention should be left as plain text instead of failing the entire operation. Use this for recoverable errors like not-found or ambiguous.
Functions ¶
func AttachmentToHTML ¶
AttachmentToHTML builds a <bc-attachment> tag for embedding in Trix-compatible HTML.
func DetectMIME ¶
DetectMIME returns the MIME type for a file path. It uses the extension map first, then falls back to reading file header bytes.
func EmbedAttachments ¶
func EmbedAttachments(html string, attachments []AttachmentRef) string
EmbedAttachments appends <bc-attachment> tags to HTML content. Each attachment is added as a separate block after the main content.
func HTMLToMarkdown ¶
HTMLToMarkdown converts HTML content to Markdown. This is useful for displaying Basecamp's rich text content in the terminal.
func Hyperlink ¶ added in v0.3.0
Hyperlink wraps text in an OSC 8 terminal hyperlink sequence. Returns text unchanged when url is empty. The URL is sanitized to strip control characters that could break out of the OSC 8 sequence or inject terminal commands.
func IsHTML ¶
IsHTML attempts to detect if the input string contains HTML. Only returns true for well-formed HTML with common content tags. Does not detect arbitrary tags like <script> to prevent XSS passthrough. Tags inside Markdown code spans (`...`) and fenced code blocks (```) are ignored.
func IsMarkdown ¶
IsMarkdown attempts to detect if the input string is Markdown rather than plain text or HTML. This is a heuristic and may not be 100% accurate.
func LinkifyMarkdownLinks ¶ added in v0.3.0
LinkifyMarkdownLinks converts markdown-style [text](url) links to OSC 8 terminal hyperlinks where the link text is clickable. Use this for rendering paths that bypass glamour (e.g., chat).
func LinkifyURLs ¶ added in v0.3.0
LinkifyURLs wraps bare URLs in OSC 8 hyperlink sequences. URLs already inside an OSC 8 sequence are not double-wrapped.
func MarkdownToHTML ¶
MarkdownToHTML converts Markdown text to HTML suitable for Basecamp's rich text fields. It handles common Markdown syntax: headings, bold, italic, links, lists, code blocks, and blockquotes. If the input already appears to be HTML, it is returned unchanged to preserve existing formatting.
func MentionToHTML ¶ added in v0.7.0
MentionToHTML builds a <bc-attachment> mention tag.
func NormalizeDragPath ¶ added in v0.3.0
NormalizeDragPath normalizes a pasted/dragged path into a filesystem path. It handles quoted paths, file:// URLs, shell-escaped characters, and tilde expansion. Only inputs that look like filesystem paths (absolute, ~/, file://, or quoted versions of these) are transformed; other inputs are returned unchanged. Returns empty for empty input.
This targets macOS and Linux terminals only. It compiles on Windows to avoid breaking cross-compilation, but Windows drag-and-drop (e.g. file:// URLs with drive letters) is not supported or tested.
func RenderMarkdown ¶
RenderMarkdown renders Markdown for terminal display using glamour. It returns styled output suitable for CLI display.
func RenderMarkdownWithWidth ¶
RenderMarkdownWithWidth renders Markdown for terminal display with a custom width.
func ValidateFile ¶
ValidateFile checks that a path refers to an existing, regular, readable file within the size limit. Returns nil on success.
Types ¶
type AttachmentRef ¶
AttachmentRef holds the metadata needed to embed a <bc-attachment> in HTML.
type MentionLookupFunc ¶ added in v0.7.0
MentionLookupFunc resolves a name to an attachable SGID and display name.
type MentionResult ¶ added in v0.7.0
MentionResult holds the resolved HTML and any mentions that could not be resolved.
func ResolveMentions ¶ added in v0.7.0
func ResolveMentions(html string, lookup MentionLookupFunc, lookupByID PersonByIDFunc) (MentionResult, error)
ResolveMentions processes mention syntax in HTML in three passes:
- Markdown mention anchors: <a href="mention:SGID">@Name</a> and <a href="person:ID">@Name</a>
- Inline @sgid:VALUE syntax
- Fuzzy @Name and @First.Last patterns
Each pass replaces matches with <bc-attachment> tags. Subsequent passes skip regions already converted by earlier passes via isInsideBcAttachment.
lookupByID may be nil if person:ID syntax is not needed; encountering a person:ID anchor with a nil lookupByID returns an error.
type ParsedAttachment ¶ added in v0.7.0
type ParsedAttachment struct {
SGID string `json:"sgid,omitempty"`
Filename string `json:"filename,omitempty"`
ContentType string `json:"content_type,omitempty"`
Filesize string `json:"filesize,omitempty"`
URL string `json:"url,omitempty"`
Href string `json:"href,omitempty"`
Width string `json:"width,omitempty"`
Height string `json:"height,omitempty"`
Caption string `json:"caption,omitempty"`
}
ParsedAttachment holds metadata extracted from a <bc-attachment> tag in HTML content.
func ParseAttachments ¶ added in v0.7.0
func ParseAttachments(content string) []ParsedAttachment
ParseAttachments extracts file attachment metadata from HTML content. It finds all <bc-attachment> tags and returns their metadata, excluding mention attachments (content-type="application/vnd.basecamp.mention").
func (*ParsedAttachment) DisplayName ¶ added in v0.7.0
func (a *ParsedAttachment) DisplayName() string
DisplayName returns the best display name: caption, then filename, then fallback.
func (*ParsedAttachment) DisplayURL ¶ added in v0.7.0
func (a *ParsedAttachment) DisplayURL() string
DisplayURL returns the best available URL for the attachment.
func (*ParsedAttachment) IsImage ¶ added in v0.7.0
func (a *ParsedAttachment) IsImage() bool
IsImage returns true if the attachment has an image content type.
type PersonByIDFunc ¶ added in v0.7.0
PersonByIDFunc resolves a person ID to an attachable SGID and canonical name. Used by the person:ID mention syntax.
Source Files