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.

Helper methods: reuse the boundary rules

The regexes behind the two factories are exposed as static helpers — InlinePattern.buildPrefixedPattern and InlinePattern.buildDelimitedPattern — for consumers that build their own InlinePattern or MarkdownComponent. You keep the fiddly parts (the email/URL-fragment boundaries, longest-name-first matching, case-insensitivity) while supplying your own builder, scopes, or component.

build_prefixed_pattern.dart

// Same boundary rules as InlinePattern.prefixed, your own pattern object —
// here to opt a TextSpan-only mention into every scope, including link labels:
InlinePattern(
  pattern: InlinePattern.buildPrefixedPattern(
    prefix: '@',
    knownNames: userDirectory.handles,
  ),
  builder: (context, match, style) => TextSpan(
    text: match.group(0),
    style: style.copyWith(color: Colors.indigo, fontWeight: FontWeight.w600),
    recognizer: TapGestureRecognizer()
      ..onTap = () => openProfile(match.group(0)!.substring(1)),
  ),
  scopes: MarkdownComponent.allScopes, // safe: builder returns a TextSpan
)

build_delimited_pattern.dart

// The delimited regex inside a custom MarkdownComponent — Discord-style
// ||spoiler|| text, with the token available as the named group 'name':
class SpoilerMd extends InlineMd {
  @override
  RegExp get exp => InlinePattern.buildDelimitedPattern(
        open: '||',
        genericTokenPattern: r'[^|\n]+', // tight, non-capturing
      );

  // Returns a WidgetSpan — keep it out of link labels (iOS paint safety).
  @override
  Set<MarkdownScope> get scopes => MarkdownComponent.allScopesExceptLinkLabel;

  @override
  InlineSpan span(BuildContext context, String text, GptMarkdownConfig config) {
    final hidden = exp.firstMatch(text)?.namedGroup('name') ?? text;
    return WidgetSpan(
      alignment: PlaceholderAlignment.baseline,
      baseline: TextBaseline.alphabetic,
      child: SpoilerChip(text: hidden, style: config.style),
    );
  }
}

In a delimited pattern the token name is captured as the named group name (and as group 1) before any group inside your genericTokenPattern, whatever that pattern contains. Write the generic pattern as tightly as the syntax allows and use non-capturing groups in it — a loose pattern such as .+ runs past the closing delimiter and swallows the rest of the line.

never_match.dart

// Empty inputs produce a regex that can never match, so an app with no
// channels yet renders its text untouched — no guard needed at the call site:
InlinePattern.prefixed(
  prefix: '#',
  knownNames: channelsFromServer, // may be empty
  builder: buildChannelSpan,
)

Both helpers return a regex that can never match when knownNames is empty and genericTokenPattern is null, and the renderer skips such a pattern entirely — so lists that load from a server can be passed straight through.

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