diff --git a/README.md b/README.md
index 06a4aa7..f295a82 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,8 @@
 [![Build Status](https://badgers.space/github/checks/rossmacarthur/pulldown-cmark-toc/trunk?label=build)](https://github.com/rossmacarthur/pulldown-cmark-toc/actions/workflows/build.yaml?branch=trunk)
 
 Generate a table of contents from a Markdown document.
+By default the heading anchor calculation (aka the "slugification")
+is done in a way that attempts to mimic GitHub's (undocumented) behavior.
 
 ## Getting started
 
diff --git a/src/lib.rs b/src/lib.rs
index ce95968..319dbeb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,9 @@
 //! Generate a table of contents from a Markdown document.
 //!
+//! By default the heading anchor calculation (aka the "slugification")
+//! is done in a way that attempts to mimic GitHub's (undocumented) behavior.
+//! (Though you can customize this with your own [`slug::Slugify`] implementation).
+//!
 //! # Examples
 //!
 //! ```