[flutter_markdown] Adopt code excerpts in README (#4656)

Updates the README to use a compiled excerpt source for its example of creating a `Markdown`. Part of flutter/flutter#102679
flutter · Aug 7, 2023 · 470a325 · 470a325
1 parent 6cb2a32
commit 470a325
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 13 deletions.
diff --git a/packages/flutter_markdown/CHANGELOG.md b/packages/flutter_markdown/CHANGELOG.md
@@ -1,6 +1,7 @@
-## NEXT
+## 0.6.17+1
 
 * Deletes deprecated splash screen meta-data element.
+* Updates README to improve examples of using Markdown.
 
 ## 0.6.17
 

diff --git a/packages/flutter_markdown/README.md b/packages/flutter_markdown/README.md
@@ -54,12 +54,18 @@ documents, respectively. GitHub Web adds header ID and emoji support. The
 Using the Markdown widget is simple, just pass in the source markdown as a
 string:
 
-    Markdown(data: markdownSource);
+<?code-excerpt "example/lib/readme_excerpts.dart (CreateMarkdown)"?>
+```dart
+const Markdown(data: markdownSource);
+```
 
 If you do not want the padding or scrolling behavior, use the MarkdownBody
 instead:
 
-    MarkdownBody(data: markdownSource);
+<?code-excerpt "example/lib/readme_excerpts.dart (CreateMarkdownBody)"?>
+```dart
+const MarkdownBody(data: markdownSource);
+```
 
 By default, Markdown uses the formatting from the current material design theme,
 but it's possible to create your own custom styling. Use the MarkdownStyle class
@@ -79,12 +85,13 @@ formatted output of the Markdown widget. For example, in the following Markdown
 widget constructor, a text string with a smiley face emoji is passed in as the
 source Markdown data.
 
+<?code-excerpt "example/lib/readme_excerpts.dart (CreateMarkdownWithEmoji)"?>
 ```dart
 Markdown(
-    controller: controller,
-    selectable: true,
-    data: 'Insert emoji here😀 ',
-)
+  controller: controller,
+  selectable: true,
+  data: 'Insert emoji here😀 ',
+);
 ```
 
 The resulting Markdown widget will contain a single line of text with the
@@ -100,18 +107,22 @@ auto-links, and strike-through. To include the inline emoji tag syntax
 while maintaining the default GitHub flavored Markdown behavior, define
 an extension set that combines EmojiSyntax with ExtensionSet.gitHubFlavored.
 
+<?code-excerpt "example/lib/readme_excerpts.dart (CreateMarkdownWithEmojiExtension)"?>
 ```dart
 import 'package:markdown/markdown.dart' as md;
-
-Markdown(
+// ···
+  Markdown(
     controller: controller,
     selectable: true,
     data: 'Insert emoji :smiley: here',
     extensionSet: md.ExtensionSet(
       md.ExtensionSet.gitHubFlavored.blockSyntaxes,
-      [md.EmojiSyntax(), ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes],
+      <md.InlineSyntax>[
+        md.EmojiSyntax(),
+        ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes
+      ],
     ),
-)
+  );
 ```
 
 ## Image Support

diff --git a/packages/flutter_markdown/example/lib/readme_excerpts.dart b/packages/flutter_markdown/example/lib/readme_excerpts.dart
@@ -0,0 +1,61 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/cupertino.dart';
+import 'package:flutter_markdown/flutter_markdown.dart';
+
+// #docregion CreateMarkdownWithEmojiExtension
+import 'package:markdown/markdown.dart' as md;
+// #enddocregion CreateMarkdownWithEmojiExtension
+
+/// Create a simple `Markdown` wdget.
+void createMarkdown() {
+  const String markdownSource = '';
+
+  // #docregion CreateMarkdown
+  const Markdown(data: markdownSource);
+  // #enddocregion CreateMarkdown
+}
+
+/// Create a simple `MarkdownBody` widget.
+void createMarkdownBody() {
+  const String markdownSource = '';
+
+  // #docregion CreateMarkdownBody
+  const MarkdownBody(data: markdownSource);
+  // #enddocregion CreateMarkdownBody
+}
+
+/// Create a simple `Markdown` widget with an emoji.
+void createMarkdownWithEmoji() {
+  final ScrollController controller = ScrollController();
+
+  // #docregion CreateMarkdownWithEmoji
+  Markdown(
+    controller: controller,
+    selectable: true,
+    data: 'Insert emoji here😀 ',
+  );
+  // #enddocregion CreateMarkdownWithEmoji
+}
+
+/// Create a simple `Markdown` widget with an emoji extension.
+void createMarkdownWithEmojiExtension() {
+  final ScrollController controller = ScrollController();
+
+  // #docregion CreateMarkdownWithEmojiExtension
+  Markdown(
+    controller: controller,
+    selectable: true,
+    data: 'Insert emoji :smiley: here',
+    extensionSet: md.ExtensionSet(
+      md.ExtensionSet.gitHubFlavored.blockSyntaxes,
+      <md.InlineSyntax>[
+        md.EmojiSyntax(),
+        ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes
+      ],
+    ),
+  );
+  // #enddocregion CreateMarkdownWithEmojiExtension
+}
diff --git a/packages/flutter_markdown/pubspec.yaml b/packages/flutter_markdown/pubspec.yaml
@@ -4,7 +4,7 @@ description: A Markdown renderer for Flutter. Create rich text output,
   formatted with simple Markdown tags.
 repository: https://github.com/flutter/packages/tree/main/packages/flutter_markdown
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+flutter_markdown%22
-version: 0.6.17
+version: 0.6.17+1
 
 environment:
   sdk: ">=3.0.0 <4.0.0"

diff --git a/script/configs/temp_exclude_excerpt.yaml b/script/configs/temp_exclude_excerpt.yaml
@@ -10,7 +10,6 @@
 - espresso
 - extension_google_sign_in_as_googleapis_auth
 - flutter_image
-- flutter_markdown
 - go_router_builder
 - google_sign_in/google_sign_in
 - image_picker_for_web