
# 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

```dart
// 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');
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      source: github:farum-azula/themes/themes/code.yml@code-v0.2.0  # 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 `SelectionArea` in a `MaterialApp`, with Cupertino's handles on iOS and macOS in a `CupertinoApp`. Without a design library it is a `SelectableRegion` with 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 `#id` scrolls to its heading; any other link goes to `onLink`.

## 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:

````markdown
```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](themes/styles-and-states.md) for the rules.

## Callouts

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

```markdown
> [!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](#the-pages-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.

```yaml
# lib/resources/application.yml
site:
  package-version: 0.7.2
spring:
  flutter:
    markdown:
      placeholders: true
```

```markdown
    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.

```dart
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.

```dart
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](../spring-boot-starter-flutter-navigation/index.md)'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](../spring-core-dart-generator/flutter/seo.md)).

## See also

- [Styles and states](themes/styles-and-states.md)
- [Typography](themes/typography.md)
- [Motion and animations](themes/motion-and-animations.md)
