diff --git a/README.md b/README.md
index 7e6ff29..6da8f85 100644
Binary files a/README.md and b/README.md differ
diff --git a/src/lib.rs b/src/lib.rs
index 90d4653..eee1b9a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -43,6 +43,8 @@
 //!   - [... in `main()`](#-in-main)
 //!   - [... diagnostic code URLs](#-diagnostic-code-urls)
 //!   - [... snippets](#-snippets)
+//!   - [... help text](#-help-text)
+//!   - [... severity level](#-severity-level)
 //!   - [... multiple related errors](#-multiple-related-errors)
 //!   - [... delayed source code](#-delayed-source-code)
 //!   - [... handler options](#-handler-options)
@@ -424,7 +426,7 @@
 //! }
 //! ```
 //!
-//! #### ... help text
+//! ### ... help text
 //! `miette` provides two facilities for supplying help text for your errors:
 //!
 //! The first is the `#[help()]` format attribute that applies to structs or
@@ -460,6 +462,19 @@
 //! };
 //! ```
 //!
+//! ### ... severity level
+//! `miette` provides a way to set the severity level of a diagnostic.
+//!
+//! ```rust
+//! use miette::Diagnostic;
+//! use thiserror::Error;
+//!
+//! #[derive(Debug, Diagnostic, Error)]
+//! #[error("welp")]
+//! #[diagnostic(severity(Warning))]
+//! struct Foo;
+//! ```
+//!
 //! ### ... multiple related errors
 //!
 //! `miette` supports collecting multiple errors into a single diagnostic, and
@@ -636,7 +651,7 @@
 //!
 //! let source = "2 + 2 * 2 = 8".to_string();
 //! let report = miette!(
-//!   labels = vec[
+//!   labels = vec![
 //!       LabeledSpan::at(12..13, "this should be 6"),
 //!   ],
 //!   help = "'*' has greater precedence than '+'",