diff --git a/docs/compiling.rst b/docs/compiling.rst
index 30cd83b..642dfe0 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -51,3 +51,67 @@
 PyPI integration, can be found in the [cmake_example]_  repository.
 
 .. [cmake_example] https://github.com/pybind/cmake_example
+
+For CMake-based projects that don't include the pybind11
+repository internally, an external installation can be detected
+through `find_package(pybind11 ... CONFIG ...)`. See the `Config file
+<https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in>`_
+docstring for details of relevant CMake variables.
+
+Once detected, and after setting any variables to guide Python and C++
+standard detection, the aforementioned ``pybind11_add_module``
+wrapper to ``add_library`` can
+be employed as described above (after ``include(pybind11Tools)``). This
+procedure is available when using CMake >= 2.8.12. A
+working example can be found at [test_installed_module]_ .
+
+.. code-block:: cmake
+
+    cmake_minimum_required(VERSION 2.8.12)
+    project(example)
+
+    find_package(pybind11 REQUIRED)
+    pybind11_add_module(example example.cpp)
+
+.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt
+
+When using a version of CMake greater than 3.0, pybind11 can
+additionally be used as a special *interface library* following the call
+to ``find_package``. CMake
+variables to guide Python and C++ standard detection should be set
+*before* ``find_package``. When ``find_package`` returns, the target
+``pybind11::pybind11`` is available with pybind11 headers, Python headers
+and libraries as needed, and C++ compile definitions attached. This
+target is suitable for linking to an independently constructed (through
+``add_library``, not ``pybind11_add_module``) target in the consuming
+project. A working example can be found at [test_installed_target]_ .
+
+.. code-block:: cmake
+
+    cmake_minimum_required(VERSION 3.0)
+    project(example)
+
+    add_library(example MODULE main.cpp)
+
+    find_package(pybind11 REQUIRED)
+    target_link_libraries(example PRIVATE pybind11::pybind11)
+    set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
+                                             SUFFIX "${PYTHON_MODULE_EXTENSION}")
+
+.. warning::
+
+    Since pybind11 is a metatemplate library, it is crucial that certain
+    compiler flags are provided to ensure high quality code generation. In
+    contrast to the ``pybind11_add_module()`` command, the CMake interface
+    library only provides the *minimal* set of parameters to ensure that the
+    code using pybind11 compiles, but it does **not** pass these extra compiler
+    flags (i.e. this is up to you).
+
+    These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
+    and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
+    (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio
+    (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
+    explanation on why these are needed.
+
+.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt
+