MarkdownView

MarkdownView shows GitHub's Markdown as Flutter widgets, in the colors and text styles of the theme shown. Headings, links, lists, tables, quotes, callouts and code blocks all follow the theme, in every app type (material, cupertino, widgets). Code blocks are colored by the theme's languages, and each has a button that copies its text.

Why

Documentation, release notes, help pages and legal texts are written in Markdown. Rendered with a generic package, they look like another app. Here they take the app's theme: a dark theme gives dark code blocks, a theme switch changes them at once, and a designer styles them in the same YAML as the rest of the app. The site you are reading shows its pages this way.

Example

// A string of Markdown; links go to the callback.
MarkdownView(text, onLink: (href) => launchUrl(Uri.parse(href)));

// A file of lib/resources/; beans.ja.md is shown instead in Japanese.
const MarkdownView.resource('resources:content/docs/beans.md');

// One block of code, exactly as a fenced block of a page.
const MarkdownView.code('server:\n  port: 8080', language: 'yaml');
# lib/resources/application.yml
spring:
  flutter:
    theme:
      source: github:farum-azula/themes/themes/[email protected]  # the languages of code
      typography:
        code: { font-family: JetBrains Mono, size: 13 }
      styles:
        code:
          background: $colors.surface-container-low
          keyword: '#C678DD'
          string: '#98C379'
          copy: true
        heading:
          color: $colors.primary
        link:
          color: $colors.secondary
        table:
          cell-width: 240
          fill: true
        callout:
          warning: '#FF5C7A'

The constructors

Constructor Parameters Shows
MarkdownView(markdown) onLink, selectable (true), outline A string of Markdown
MarkdownView.resource(location) onLink, selectable (true), outline A resource (resources:content/beans.md), in the app's language when a translation exists next to it (beans.ja.md), and follows the language. It keeps the page shown until the next one is read, then changes the theme's way (motion.content-change)
MarkdownView.code(code) language, selectable (true) One block of code

Headings and text

The headings take the sizes of the typography (# is headline-large, ## headline-medium, ### headline-small, then title-large, title-medium, title-small), the text body-large. In a WidgetsApp, which has no Material Theme, the theme's text styles are used with the Material 3 sizes of the starter's type scale (SpringTypeScale) for the locale's script.

Key Default Meaning
styles.heading.color the text's color The color of every heading
styles.heading.h1 ... styles.heading.h6 styles.heading.color The color of one level
styles.link.color $colors.primary Links

Tables

A table's column is as wide as its text, up to cell-width, where the text wraps. A table wider than the view scrolls sideways instead of squeezing its columns, so it reads on a phone. A table narrower than the view widens its columns to the view's width, so it lines up with the text around it.

Key Default Meaning
styles.table.cell-width 280 The widest a column grows before its text wraps
styles.table.fill true Widen a narrow table to the view's width; false keeps it as wide as its text

Code

Code, inline and in fenced blocks, uses the code text style (typography.code) and the colors of styles.code. Every key is optional; without them the code follows the color scheme.

Key Default What it colors or sets
styles.code.background $colors.surface-container-highest The block's fill and inline code's background
styles.code.text the code text style's color Everything not listed below
styles.code.keyword $colors.primary Keywords, true, false, null
styles.code.string $colors.tertiary Strings, and unquoted YAML and .properties values
styles.code.comment $colors.outline Comments
styles.code.number $colors.secondary Numbers, with a unit too (120ms, 35%)
styles.code.key $colors.primary Keys of YAML, .properties and JSON; options of a shell command
styles.code.annotation $colors.secondary Annotations, YAML tags
styles.code.variable $colors.on-tertiary-container References and placeholders ($colors.primary, ${PORT}, $HOME, YAML anchors)
styles.code.type $colors.on-secondary-container Type names
styles.code.punctuation $colors.on-surface-variant Brackets, braces, commas, colons
styles.code.inline-text the code text style's color Inline code
styles.code.inline-background background Inline code's background
styles.code.header background The header of a block with a title
styles.code.title $colors.on-surface-variant A block's title and its copy button
styles.code.padding 12 Insets inside the block: 16, [16, 12]
styles.code.radius 6 Corner radius
styles.code.border none Border color
styles.code.border-width 1 Border width, when border is set
styles.code.copy true A button that copies the block's text: in the header of a block with a title, in the corner of the others; false for none

A fenced block with a title after its language gets a header with the title and the copy button:

```dart title="lib/orders.dart"
@Service()
class OrderService { ... }
```

The languages of code

The starter knows no language by itself. What the code of a fenced block is made of comes from the theme's syntax.<language>: rules of regular expressions and kinds tried in order, keywords, types and aliases. A block in a language no theme has is plain text in the text color.

You rarely write a language yourself. The farum-azula/themes repository has Dart, Java, YAML, properties, shell and JSON in one file; download it for every theme with source on spring.flutter.theme (as in the example above). A syntax.<language> you write wins over the downloaded one. See Styles and states for the rules.

Callouts

GitHub's callouts are boxes in their kind's color, with the kind's name as a title:

> [!WARNING]
> A missing bean stops the start.
Key Default Kind
styles.callout.note primary [!NOTE]
styles.callout.tip tertiary [!TIP]
styles.callout.important secondary [!IMPORTANT]
styles.callout.warning error [!WARNING]
styles.callout.caution error [!CAUTION]

The titles are the messages markdown.alert.<kind> (Note, Tip, ... without them), so messages_ja.properties translates them.

Long pages

A long page comes in over a few frames: the top in the first frame, the rest a part each next frame (about 3000 characters of text per frame; a table cell counts more). So no single frame builds and lays out the whole page. A page of tables used to take a fifth of a second in one frame on the web.

MarkdownOutline.show(id) of a heading that is not built yet builds the rest of the page first, then scrolls there, so the page's headings work at once.

A table of more than 30 rows measures its columns once, from their 4 longest cells (up to styles.table.cell-width), and adds its rows a few at a frame (about 1500 characters per frame). It does not measure every cell twice. Shorter tables are built as before. There is nothing to configure.

Values from the configuration

With spring.flutter.markdown.placeholders: true, each {{key}} of a page is replaced by the value of the configuration's key, code blocks included. A key without a value stays as it is, so the placeholders of other tools ({{baseUrl}} of an HTTP file) are kept, and \{{ writes {{ as text. ${...} is not touched: it is the configuration's own placeholder, and pages show it in examples.

# lib/resources/application.yml
site:
  package-version: 0.7.2
spring:
  flutter:
    markdown:
      placeholders: true
    spring_boot_starter_cache: ^{{site.package-version}}

The page shows spring_boot_starter_cache: ^0.7.2. The build's pages for search engines, their Markdown copies and llms.txt replace the placeholders the same way. This site writes the latest release into site.package-version before each build, so its dependency examples never need an edit after a release.

The page's headings

MarkdownOutline gets the headings of the page a MarkdownView shows, each with GitHub's anchor (## Bean methods is #bean-methods), for an "On this page" list. show(id) scrolls to one.

final outline = MarkdownOutline();

MarkdownView.resource('resources:content/docs/beans.md', outline: outline);

// The list of the page's sections.
ListenableBuilder(
  listenable: outline,
  builder: (context, _) => Column(children: [
    for (final heading in outline.headings.where((h) => h.level == 2))
      TextButton(
        onPressed: () => outline.show(heading.id),
        child: Text(heading.text),
      ),
  ]),
);

The heading being read

outline.current is the heading being read as the page scrolls: the last one that has reached the top part of the screen. It notifies only when the reader comes to another heading, so a list that marks its entry is built again once a section, not at every step of the scroll. currentAmong(shown) gives the entry to mark in a list that shows only some levels.

ListenableBuilder(
  listenable: Listenable.merge([outline, outline.current]),
  builder: (context, _) {
    final shown = outline.headings.where((h) => h.level == 2).toList();
    final reading = outline.currentAmong(shown);
    return Column(children: [
      for (final heading in shown)
        Entry(heading, selected: heading == reading),
    ]);
  },
);
When What is current
Above the first heading null
Inside a ### of a section That heading; currentAmong of the second-level ones gives its ##
At the end of the page The last heading on the screen, though it never reaches the top
After show(id) That heading at once, and until the reader scrolls again

The MarkdownView keeps it up to date from the scrollable it is in; nothing is wired by hand.

With navigation

spring_boot_starter_flutter_navigation's RouteContentView shows a route's Markdown (@ScreenRoute(content: ...)) with MarkdownView, and an address with an anchor (/docs/beans#scopes) opens at its heading. The same Markdown files can become HTML pages for search engines (see Pages for search engines).

See also