diff --git a/.gitignore b/.gitignore
index 4b89fda..c19a678 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,8 @@
+# NOTE - do not put any .md files or directories that contain .md files that
+# gitbook needs to access in this file, or they won't be shown - upstream bugs:
+# https://github.com/GitbookIO/gitbook/issues/931
+# https://github.com/GitbookIO/gitbook/issues/1845
+
 npm-debug.log
 _book/
-node_modules/
\ No newline at end of file
+node_modules/