diff --git a/CHANGELOG.md b/CHANGELOG.md
index b956487..b23b34c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,9 @@
+## 1.0.11
+
+* Overhauled the README: added a feature list, installation instructions, a widget comparison (`Markdown` / `MarkdownBody` / `MarkdownRaw`), and code examples for link handling (`onTapLink`), `MarkdownStyleSheet` styling, and custom element builders
+* Added screenshots to the pub.dev listing showcasing rich-text formatting, GitHub Flavored Markdown tables and task lists, and code blocks
+* Pointed the `documentation` link at the generated API docs on pub.dev
+
 ## 1.0.10
 
 * Added a `contextMenuBuilder` parameter to `Markdown` and `MarkdownBody`, letting callers customise or suppress (pass `null`) the text-selection toolbar shown when `selectable` is enabled. Defaults to the platform-adaptive Flutter selection toolbar, so existing behaviour is unchanged (#134)
diff --git a/README.md b/README.md
index 624d94c..9365cfe 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,40 @@ For historical context, see the [original flutter_markdown package](https://pub.
 
 **LaTeX Support:** For LaTeX rendering support, check out the [`flutter_markdown_plus_latex`](https://pub.dev/packages/flutter_markdown_plus_latex) package.
 
+## Features
+
+- **GitHub Flavored Markdown** by default — headings, bold/italic, strikethrough, blockquotes, lists, and horizontal rules.
+- **Tables** with customisable borders, cell alignment, and per-column widths.
+- **Task lists** rendered as checkboxes.
+- **Fenced and inline code** with independent per-block horizontal scrolling and selection highlighting.
+- **Links** with a tap callback, and **images** from the network, local files, or bundled assets.
+- **Footnotes** and **emoji** (Unicode or `:shortcode:` syntax).
+- **Text selection** with `onSelectionChanged`, a tap handler, and a customisable selection toolbar via `contextMenuBuilder`.
+- **Three widgets** for different layouts: scrollable `Markdown`, inline `MarkdownBody`, and unstyled `MarkdownRaw`.
+- **Deep styling** through `MarkdownStyleSheet`, plus **custom element and padding builders** for full control over rendering.
+- **`noScroll`** mode to embed rendered Markdown inside an existing scroll view.
+- Runs on **Android, iOS, web, macOS, Windows, and Linux**.
+
+## Screenshots
+
+| Rich text & formatting | Tables & task lists | Code blocks |
+| :---: | :---: | :---: |
+| ![Rich text and formatting](screenshots/formatting.png) | ![Tables and task lists](screenshots/tables.png) | ![Code blocks](screenshots/code.png) |
+
+## Installation
+
+Add the package to your project:
+
+```bash
+flutter pub add flutter_markdown_plus
+```
+
+Then import it where you need it:
+
+```dart
+import 'package:flutter_markdown_plus/flutter_markdown_plus.dart';
+```
+
 A markdown renderer for Flutter. It supports the
 [original format](https://daringfireball.net/projects/markdown/), but no inline
 HTML.
@@ -89,6 +123,62 @@ but it's possible to create your own custom styling. Use the MarkdownStyle class
 to pass in your own style. If you don't want to use Markdown outside of material
 design, use the MarkdownRaw class.
 
+### Choosing a widget
+
+| Widget | Use it when |
+| --- | --- |
+| `Markdown` | You want a standalone, scrollable view of the content. |
+| `MarkdownBody` | You want to embed rendered Markdown inside your own layout; it sizes itself to its content. |
+| `MarkdownRaw` | You want the rendering without Material theming. |
+
+To render inside an existing scroll view (for example a `CustomScrollView` or a
+`Column` in a `SingleChildScrollView`), use `Markdown` with `noScroll: true` so it
+lays out as a non-scrolling `Column` instead of managing its own scrolling.
+
+## Handling Links
+
+Markdown links are not followed automatically — you decide what a tap does.
+Provide an `onTapLink` callback and open the URL yourself, for example with the
+[`url_launcher`](https://pub.dev/packages/url_launcher) package:
+
+```dart
+Markdown(
+  data: '[Flutter](https://flutter.dev)',
+  onTapLink: (String text, String? href, String title) {
+    if (href != null) {
+      launchUrl(Uri.parse(href));
+    }
+  },
+);
+```
+
+## Styling
+
+Pass a `MarkdownStyleSheet` to restyle any element. The easiest approach is to
+start from the current theme and override only what you need with `copyWith`:
+
+```dart
+MarkdownBody(
+  data: markdownSource,
+  styleSheet: MarkdownStyleSheet.fromTheme(Theme.of(context)).copyWith(
+    h1: Theme.of(context).textTheme.headlineMedium,
+    code: const TextStyle(
+      fontFamily: 'monospace',
+      backgroundColor: Color(0x11000000),
+    ),
+    blockquotePadding: const EdgeInsets.all(12),
+  ),
+);
+```
+
+## Custom Rendering
+
+For full control over how a specific tag renders, supply a
+`MarkdownElementBuilder` through the `builders` map, and fine-tune spacing with
+`paddingBuilders`. This lets you swap in your own widgets for elements such as
+`code`, `a`, or custom tags. See the [`example/`](example/) app for working
+custom-builder demos.
+
 ## Selection
 
 By default, Markdown is not selectable. A caller may use the following ways to
diff --git a/pubspec.yaml b/pubspec.yaml
index 9fd37de..67a4f99 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -4,8 +4,8 @@ description: A Markdown renderer for Flutter. Create rich text output,
   formatted with simple Markdown tags.
 repository: https://github.com/foresightmobile/flutter_markdown_plus
 issue_tracker: https://github.com/foresightmobile/flutter_markdown_plus/issues
-documentation: https://github.com/foresightmobile/flutter_markdown_plus#readme
-version: 1.0.10
+documentation: https://pub.dev/documentation/flutter_markdown_plus/latest/
+version: 1.0.11
 
 environment:
   sdk: ^3.4.0
@@ -30,5 +30,13 @@ topics:
   - markdown
   - widgets
 
+screenshots:
+  - description: Rich text, emphasis, blockquotes and lists rendered from Markdown.
+    path: screenshots/formatting.png
+  - description: GitHub Flavored Markdown tables and task-list checkboxes.
+    path: screenshots/tables.png
+  - description: Fenced and inline code blocks with monospace styling.
+    path: screenshots/code.png
+
 formatter:
   page_width: 120
diff --git a/screenshots/code.png b/screenshots/code.png
new file mode 100644
index 0000000..4a024b1
Binary files /dev/null and b/screenshots/code.png differ
diff --git a/screenshots/formatting.png b/screenshots/formatting.png
new file mode 100644
index 0000000..a5a51bd
Binary files /dev/null and b/screenshots/formatting.png differ
diff --git a/screenshots/tables.png b/screenshots/tables.png
new file mode 100644
index 0000000..308100e
Binary files /dev/null and b/screenshots/tables.png differ