Inline syntax

Render standard Markdown links correctly, then layer your product's own tokens—mentions, channels, emoji, issue references, or template tags—into the same flowing text.

Autolinks

Bare URLs, www. hosts, email addresses, and angle-bracket autolinks become links without pre-processing. The parser follows GFM-style boundary rules, so surrounding punctuation and balanced parentheses stay out of the destination.

reply.dart

GptMarkdown(
  'Ship it: https://pub.dev or mail ada@example.com',
  onLinkTap: (url, title) => launchUrlString(url),
)

Input	Result
see https://x.com.	The period stays outside the link.
(https://x.com)	The unbalanced closing parenthesis stays outside.
https://en.wikipedia.org/wiki/Foo_(bar)	Balanced parentheses stay inside.
www.example.com	Links as `http://www.example.com`.
ada@example.com	Links as `mailto:ada@example.com`.
https://x.com	Renders as a bold link; the bold markers never enter the destination.
`https://x.com`	Remains code, not a link.

Angle autolinks such as <https://x.com>, <mailto:a@b.com>, and <a@b.com> follow CommonMark's deliberate-author syntax and accept any scheme. Bare links remain limited to the allowlist shown above.

links.dart

// Bare http, https, mailto, and xmpp links work automatically.
// Add app-specific URL schemes only when your product expects them:
GptMarkdown(
  text,
  autolinkSchemes: const {'myapp', 'slack'},
)

// Or leave bare URLs as plain text. Explicit [label](url) links still work.
GptMarkdown(text, autolink: false)

Avoid a URL pre-processor.

Rewriting bare URLs into Markdown links before rendering can capture punctuation or formatting markers. Let the inline parser see the surrounding syntax first, or turn autolink off if a legacy pre-processor must remain.

App-specific tokens with InlinePattern

InlinePattern is the recommended extension point for inline product syntax. Patterns are matched before built-in inline components, so a matching pattern deliberately takes precedence.

issue_pattern.dart

import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
import 'package:gpt_markdown/gpt_markdown.dart';

GptMarkdown(
  text,
  inlinePatterns: [
    InlinePattern(
      pattern: RegExp(r'(?<![\w-])GH-(\d+)\b'),
      builder: (context, match, style) => TextSpan(
        text: match.group(0),
        style: style.copyWith(
          color: Theme.of(context).colorScheme.primary,
          fontWeight: FontWeight.w600,
        ),
        recognizer: TapGestureRecognizer()
          ..onTap = () => openIssue(match.group(1)!),
      ),
      // TextSpan is safe to opt into every Markdown scope.
      scopes: MarkdownComponent.allScopes,
    ),
  ],
)

Use lookarounds and word boundaries to describe a token's actual boundaries. Patterns are matched against the whole document, so ^ and $ are rarely the right anchors.

Mentions and channels

Use InlinePattern.prefixed for @name and #channel. It knows not to claim an @ inside an email address or a # inside a URL fragment, and longer known names win over shorter ones.

channels.dart

// Recommended: only known names match.
InlinePattern.prefixed(
  prefix: '#',
  knownNames: myChannelNames, // ['general', 'design-review', ...]
  builder: (context, match, style) => WidgetSpan(
    alignment: PlaceholderAlignment.baseline,
    baseline: TextBaseline.alphabetic,
    child: ChannelChip(name: match.group(0)!.substring(1)),
  ),
)

// This avoids treating #2959, a URL fragment, or a hex colour as a channel.
//
// Opt in only when every token is meaningful in your product:
InlinePattern.prefixed(
  prefix: '#',
  knownNames: myChannelNames,
  genericTokenPattern: r'[A-Za-z0-9_][A-Za-z0-9_-]*',
  builder: (context, match, style) => TextSpan(
    text: match.group(0),
    style: style,
  ),
)

Use known names by default. A generic # fallback can turn issue numbers, mid-sentence headings, and colors into chips. Matching is case-insensitive.

Emoji and delimited syntax

InlinePattern.delimited handles closing delimiters that a prefixed token cannot express. It keeps ordinary times such as 10:30:45 and URLs with ports from becoming shortcodes.

emoji.dart

const emoji = {'tada': '🎉', 'rocket': '🚀', 'fire': '🔥'};

InlinePattern.delimited(
  open: ':',
  knownNames: emoji.keys,
  builder: (context, match, style) {
    final name = match.namedGroup('name');
    final glyph = name == null ? null : emoji[name];
    return TextSpan(text: glyph ?? match.group(0), style: style);
  },
)

// Delimited patterns can also be asymmetric or multi-character:
InlinePattern.delimited(
  open: '{{',
  close: '}}',
  knownNames: templateNames,
  builder: buildTemplateSpan,
)

The token is available as the named name group (and group 1), even when a generic token pattern includes its own groups. Boundaries prevent :tada:xyz from matching while adjacent :fire::fire: tokens still match twice. Return the raw match for an unknown name so author text never becomes an empty gap.

TextSpan, WidgetSpan, and scopes

Prefer a TextSpan whenever your token can be text. It wraps, participates in selection, and aligns to the surrounding baseline. A WidgetSpan is for a real chip, icon, or image.

inline_ui.dart

// A TextSpan wraps, remains selectable, and stays on the text baseline.
builder: (context, match, style) => TextSpan(
  text: match.group(0),
  style: style,
)

// Use WidgetSpan only for actual UI. The package compensates for text scaling
// when InlinePattern returns one:
builder: (context, match, style) => WidgetSpan(
  alignment: PlaceholderAlignment.middle,
  child: Icon(Icons.tag, size: (style.fontSize ?? 14) * 1.15),
)

Scope safety matters.

A widget inside a Markdown link label becomes a nested placeholder and can disappear on iOS. Patterns default to MarkdownComponent.allScopesExceptLinkLabel; keep that default for widget-based UI. Without it, [#design](https://example.com) can become blank on iOS with no visible error. Opt into MarkdownComponent.allScopes only when returning a safe TextSpan.

Common mistakes

Returning an empty span for an unknown token. Return the original match so the author's text never vanishes.
Building the pattern list on every frame. Cache it in a field or make it const; list identity participates in rendering work.
Using a custom component for a simple token. Start with InlinePattern; use a component only for genuinely new Markdown syntax.

Markdown & AI output Custom components