add crate-level docs for syntax highlighting

src/lib.rs

@@ -47,6 +47,7 @@
 //!   - [... delayed source code](#-delayed-source-code)
 //!   - [... handler options](#-handler-options)
 //!   - [... dynamic diagnostics](#-dynamic-diagnostics)
+//!   - [... syntax highlighting](#-syntax-highlighting)
 //! - [Acknowledgements](#acknowledgements)
 //! - [License](#license)
 //!
@@ -625,6 +626,23 @@
 //! println!("{:?}", report)
 //! ```
 //!
+//! ### ... syntax highlighting
+//!
+//! When rendering in graphical mode, `miette` can be configured to highlight
+//! source code snippets like this:
+//!
+//! <!-- TODO: screenshot goes here once default Theme is decided -->
+//!
+//! To use the built-in highlighting functionality, you must enable the
+//! `syntect-highlighter` crate feature. When activated, `miette` will
+//! automatically use the [`syntect`] crate to highlight the `#[source_code]`
+//! field of your [`Diagnostic`].
+//!
+//! If you want to use your own custom highlighter, you can use the
+//! [`MietteHandlerOpts::with_syntax_highlighting`] method to provide a
+//! custom implementation of the [`Highlighter`](highlighters::Highlighter)
+//! trait. See the [`highlighters`] module docs for more details.
+//!
 //! ## Acknowledgements
 //!
 //! `miette` was not developed in a void. It owes enormous credit to various