MarkdownView

MarkdownView は、GitHub の Markdown を、表示中のテーマの色とテキストスタイルで Flutter のウィジェットとして表示します。見出し、リンク、リスト、表、引用、コールアウト、コードブロックはすべて、どのアプリの種類 (material、cupertino、widgets) でもテーマに従います。コードブロックはテーマの言語で色付けされ、それぞれにテキストをコピーするボタンがあります。

使う理由

ドキュメント、リリースノート、ヘルプページ、法的なテキストは Markdown で書かれます。汎用のパッケージで描画すると、別のアプリのように見えます。ここではそれらはアプリのテーマを使います。ダークテーマならコードブロックも暗くなり、テーマを切り替えると即座に変わり、デザイナーはアプリの残りと同じ YAML でスタイルを付けます。今読んでいるサイトも、この方法でページを表示しています。

例

// Markdown の文字列。リンクはコールバックに渡される。
MarkdownView(text, onLink: (href) => launchUrl(Uri.parse(href)));

// lib/resources/ のファイル。日本語では代わりに beans.ja.md が表示される。
const MarkdownView.resource('resources:content/docs/beans.md');

// ページのフェンス付きブロックとまったく同じ、一つのコードブロック。
const MarkdownView.code('server:\n  port: 8080', language: 'yaml');
# lib/resources/application.yml
spring:
  flutter:
    theme:
      source: github:farum-azula/themes/themes/[email protected]  # コードの言語
      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'

コンストラクター

コンストラクター パラメーター 表示するもの
MarkdownView(markdown) onLink、selectable (true)、outline Markdown の文字列
MarkdownView.resource(location) onLink、selectable (true)、outline リソース (resources:content/beans.md)。隣に翻訳 (beans.ja.md) があればアプリの言語で表示し、言語に追従する。次のページが読まれるまで表示中のページを保ち、その後テーマの方法 (motion.content-change) で切り替える
MarkdownView.code(code) language、selectable (true) 一つのコードブロック

見出しとテキスト

見出しはタイポグラフィのサイズを使い (# は headline-large、## は headline-medium、### は headline-small、次に title-large、title-medium、title-small)、テキストは body-large を使います。Material の Theme を持たない WidgetsApp では、テーマのテキストスタイルが、ロケールの文字体系に応じた、スターターのタイプスケール (SpringTypeScale) の Material 3 のサイズで使われます。

キー デフォルト 意味
styles.heading.color テキストの色 すべての見出しの色
styles.heading.h1 ... styles.heading.h6 styles.heading.color 一つのレベルの色
styles.link.color $colors.primary リンク

表

表の列はそのテキストの幅になり、最大で cell-width まで広がり、そこでテキストが折り返されます。ビューより広い表は、列を詰める代わりに横にスクロールするため、スマートフォンでも読めます。ビューより狭い表は、周りのテキストと揃うよう、列をビューの幅まで広げます。

キー デフォルト 意味
styles.table.cell-width 280 テキストが折り返される前に列が広がる最大の幅
styles.table.fill true 狭い表をビューの幅まで広げる。false はテキストの幅のままにする

コード

インラインとフェンス付きブロックのコードは、code テキストスタイル (typography.code) と styles.code の色を使います。どのキーも省略でき、なければコードはカラースキームに従います。

キー デフォルト 色付けまたは設定するもの
styles.code.background $colors.surface-container-highest ブロックの塗りとインラインコードの背景
styles.code.text code テキストスタイルの色 以下に挙げないものすべて
styles.code.keyword $colors.primary キーワード、true、false、null
styles.code.string $colors.tertiary 文字列、引用符のない YAML と .properties の値
styles.code.comment $colors.outline コメント
styles.code.number $colors.secondary 数値。単位付きのもの (120ms、35%) も
styles.code.key $colors.primary YAML、.properties、JSON のキー。シェルコマンドのオプション
styles.code.annotation $colors.secondary アノテーション、YAML のタグ
styles.code.variable $colors.on-tertiary-container 参照とプレースホルダー ($colors.primary、${PORT}、$HOME、YAML のアンカー)
styles.code.type $colors.on-secondary-container 型の名前
styles.code.punctuation $colors.on-surface-variant 括弧、波括弧、カンマ、コロン
styles.code.inline-text code テキストスタイルの色 インラインコード
styles.code.inline-background background インラインコードの背景
styles.code.header background タイトルを持つブロックのヘッダー
styles.code.title $colors.on-surface-variant ブロックのタイトルとそのコピーボタン
styles.code.padding 12 ブロックの内側の余白: 16、[16, 12]
styles.code.radius 6 角の半径
styles.code.border なし 枠線の色
styles.code.border-width 1 border が設定されている場合の枠線の幅
styles.code.copy true ブロックのテキストをコピーするボタン。タイトルを持つブロックではヘッダーに、それ以外では隅に置く。false でなし

言語の後に title を持つフェンス付きブロックは、タイトルとコピーボタンを持つヘッダーを得ます。

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

コードの言語

スターター自体はどの言語も知りません。フェンス付きブロックのコードが何でできているかは、テーマの syntax.<language> から来ます。順に試される正規表現と種類のルール、keywords、types、aliases です。どのテーマも持たない言語のブロックは、text の色のプレーンテキストになります。

言語を自分で書くことはまれです。farum-azula/themes リポジトリには、Dart、Java、YAML、プロパティ、シェル、JSON が一つのファイルにあります。spring.flutter.theme の source で、すべてのテーマのためにそれをダウンロードしてください (上の例のように)。自分で書いた syntax.<language> は、ダウンロードしたものより優先されます。ルールについては スタイルと状態 を参照してください。

コールアウト

GitHub のコールアウトは、その種類の色の、種類の名前をタイトルとするボックスです。

> [!WARNING]
> A missing bean stops the start.
キー デフォルト 種類
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]

タイトルはメッセージ markdown.alert.<kind> です (なければ Note、Tip など)。そのため messages_ja.properties で翻訳できます。

長いページ

長いページは数フレームに分けて表示されます。最初のフレームで先頭を、次のフレームごとに残りを一部ずつ表示します (1 フレームあたりテキスト約 3000 文字。表のセルはそれより多く数えます)。そのため、1 つのフレームでページ全体をビルドしてレイアウトすることはありません。表だらけのページは、以前は Web で 1 フレームに 5 分の 1 秒かかっていました。

まだビルドされていない見出しに対する MarkdownOutline.show(id) は、先にページの残りをビルドしてからそこへスクロールするので、ページの見出し はすぐに使えます。

30 行を超える表は、列の幅を 4 つの最も長いセルから一度だけ測り (styles.table.cell-width まで)、行を 1 フレームに少しずつ (1 フレームあたり約 1500 文字) 追加します。すべてのセルを 2 回測ることはありません。短い表はこれまでどおりです。設定するものはありません。

設定の値

spring.flutter.markdown.placeholders: true にすると、ページの {{key}} はそれぞれ、設定のそのキーの値に置き換わります。コードブロックの中もです。値のないキーはそのまま残るので、ほかのツールのプレースホルダー (HTTP ファイルの {{baseUrl}}) は保たれます。\{{ は {{ という文字として書き出されます。${...} には触れません。これは設定そのもののプレースホルダーで、ページは例としてそれを見せるからです。

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

ページには spring_boot_starter_cache: ^0.7.2 と表示されます。検索エンジン向けにビルドが書くページ、その Markdown のコピー、llms.txt も同じようにプレースホルダーを置き換えます。このサイトはビルドのたびに最新のリリースを site.package-version に書き込むので、依存関係の例はリリースのあとも書き直す必要がありません。

ページの見出し

MarkdownOutline は、MarkdownView が表示するページの見出しを、それぞれ GitHub のアンカー (## Bean methods は #bean-methods) とともに受け取ります。「このページの内容」のリストに使います。show(id) はその一つまでスクロールします。

final outline = MarkdownOutline();

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

// ページのセクションのリスト。
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),
      ),
  ]),
);

読んでいる見出し

outline.current は、ページをスクロールしている間に読んでいる見出しです。画面の上の部分に達した最後の見出しです。読み手が別の見出しに来たときだけ通知するので、自分の項目に印を付けるリストは、スクロールの一歩ごとではなく、セクションごとに一度だけ再構築されます。currentAmong(shown) は、一部のレベルだけを表示するリストで印を付ける項目を返します。

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),
    ]);
  },
);
いつ 現在の見出し
最初の見出しより上 null
セクションの ### の中 その見出し。第 2 レベルの見出しで currentAmong を呼ぶと、その ## を返します
ページの終わり 画面にある最後の見出し。上まで届かなくてもそうなります
show(id) の後 ただちにその見出し。読み手がもう一度スクロールするまで続きます

MarkdownView が、自分が入っているスクロール領域から最新の状態に保ちます。手で配線するものはありません。

ナビゲーションとともに

spring_boot_starter_flutter_navigation の RouteContentView は、ルートの Markdown (@ScreenRoute(content: ...)) を MarkdownView で表示し、アンカー付きのアドレス (/docs/beans#scopes) はその見出しで開きます。同じ Markdown ファイルは、検索エンジンのための HTML ページにもなります (検索エンジン向けのページ を参照)。

関連項目