diff --git a/layouts/shortcodes/README.md b/layouts/shortcodes/README.md
new file mode 100644
index 0000000..07cd229
--- /dev/null
+++ b/layouts/shortcodes/README.md
@@ -0,0 +1,17 @@
+Short codes provide code utility in content files. They can call partials but not other short codes.
+
+`comment.html` is intentionally blank, it allows comments in content files which do nothing.
+
+For block comments, use `hide.html` such as:
+
+```
+{{< hide >}}
+lalala
+
+this is markdown content
+
+# secret section not published yet
+
+super duper unfinished content
+{{< /hide >}}
+```