diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index c030ac73..6087125f 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -14,6 +14,7 @@ set(glfw_DOCS_SOURCES
     "${GLFW_SOURCE_DIR}/docs/window.dox"
     "${GLFW_SOURCE_DIR}/docs/input.dox"
     "${GLFW_SOURCE_DIR}/docs/vulkan.dox"
+    "${GLFW_SOURCE_DIR}/docs/metal.dox"
     "${GLFW_SOURCE_DIR}/docs/compat.dox")
 
 if (GLFW_DOCUMENT_INTERNALS)
diff --git a/docs/main.dox b/docs/main.dox
index fc95cc4e..a030100e 100644
--- a/docs/main.dox
+++ b/docs/main.dox
@@ -34,6 +34,8 @@ use the new API.
 There is a section on @ref guarantees_limitations for pointer lifetimes,
 reentrancy, thread safety, event order and backward and forward compatibility.
 
+The @ref metal shows how to use Metal with GLFW on OS X.
+
 The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
 design, implementation and use of GLFW.
 
diff --git a/docs/metal.dox b/docs/metal.dox
new file mode 100644
index 00000000..ad2da1ce
--- /dev/null
+++ b/docs/metal.dox
@@ -0,0 +1,7 @@
+/*!
+
+@page metal Metal guide
+ 
+@tableofcontents
+
+*/