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 |
- HTML written in the Markdown is shown as text. A front matter (
---...---) is left out. - The text can be selected the way of the app's design library: with Material's
SelectionAreain aMaterialApp, with Cupertino's handles on iOS and macOS in aCupertinoApp. Without a design library it is aSelectableRegionwith no menu and the starter's own handles (SpringTextSelectionControls): none where a mouse selects, two round handles in the theme's primary color on a touch screen. - A link to
#idscrolls to its heading; any other link goes toonLink.
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).