From 44f3ae212d85a60750769df0e9fa8022274166c8 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan.limberg@icloud.com>
Date: Wed, 12 Feb 2020 16:34:33 -0500
Subject: [PATCH] Ensure nested dot files in themes are ignored.

Also, document how all files within themes are treated by MkDocs.
Fixes #1981.
---
 docs/about/release-notes.md          |  1 +
 docs/user-guide/custom-themes.md     | 41 ++++++++++++++++++++++++++++
 mkdocs/structure/files.py            |  3 +-
 mkdocs/tests/structure/file_tests.py |  6 +++-
 4 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md
index e5e3c66a..daf977e4 100644
--- a/docs/about/release-notes.md
+++ b/docs/about/release-notes.md
@@ -72,6 +72,7 @@ do, adding `--strict`, `--theme`, `--theme-dir`, and `--site-dir`.
 
 ### Other Changes and Additions to Version 1.1
 
+* Bugfix: Ensure nested dot files in themes are ignored and document behavior (#1981).
 * Update minimum dependancy to Markdown 3.0.1.
 * Updated minimum dependancy to Jinja 2.10.1 to address security
   concerns (#1780).
diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md
index 754a05dc..e5003468 100644
--- a/docs/user-guide/custom-themes.md
+++ b/docs/user-guide/custom-themes.md
@@ -117,6 +117,47 @@ with one of the [built-in themes] and modify it accordingly.
 [theme_dir]: ./styling-your-docs.md#using-the-theme_dir
 [blocks]: ./styling-your-docs.md#overriding-template-blocks
 
+## Theme Files
+
+There are various files which a theme treats special in some way. Any other
+files are simply copied from the theme directory to the same path in the
+`site_dir` when the site it built. For example image and CSS files have no
+special significance and are copied as-is. Note, however, that if the user
+provides a file with the same path in their `docs_dir`, then the user's file
+will replace the theme file.
+
+### Template Files
+
+Any files with the `.html` extension are considered to be template files and are
+not copied from the theme directory or any subdirectories. Also, any files
+listed in [static_templates] are treated as templates regardless of their file
+extension.
+
+[static_templates]: #static_templates
+
+### Theme Meta Files
+
+The various files required for packaging a theme are also ignored. Specifically,
+the `mkdocs_theme.yml` configuration file and any Python files.
+
+### Dot Files
+
+Theme authors can explicitly force MkDocs to ignore files by starting a file or
+directory name with a dot. Any of the following files would be ignored:
+
+```text
+.ignored.txt
+.ignored/file.txt
+foo/.ignored.txt
+foo/.ignored/file.txt
+```
+
+### Documentation Files
+
+All documentation files are ignored. Specifically, any Markdown files (using any
+of the file extensions supported by MKDocs). Additionally, any README files
+which may exist in the theme directories are ignored.
+
 ## Template Variables
 
 Each template in a theme is built with a template context. These are the
diff --git a/mkdocs/structure/files.py b/mkdocs/structure/files.py
index b10dd4b3..a693fadb 100644
--- a/mkdocs/structure/files.py
+++ b/mkdocs/structure/files.py
@@ -64,7 +64,8 @@ class Files:
     def add_files_from_theme(self, env, config):
         """ Retrieve static files from Jinja environment and add to collection. """
         def filter(name):
-            patterns = ['.*', '*.py', '*.pyc', '*.html', '*readme*', 'mkdocs_theme.yml']
+            # '.*' filters dot files/dirs at root level whereas '*/.*' filters nested levels
+            patterns = ['.*', '*/.*', '*.py', '*.pyc', '*.html', '*readme*', 'mkdocs_theme.yml']
             patterns.extend('*{}'.format(x) for x in utils.markdown_extensions)
             patterns.extend(config['theme'].static_templates)
             for pattern in patterns:
diff --git a/mkdocs/tests/structure/file_tests.py b/mkdocs/tests/structure/file_tests.py
index 59bcdb8b..5712ed66 100644
--- a/mkdocs/tests/structure/file_tests.py
+++ b/mkdocs/tests/structure/file_tests.py
@@ -323,7 +323,11 @@ class TestFiles(PathAssertionMixin, unittest.TestCase):
         'favicon.ico',
         'style.css',
         'foo.md',
-        'README'
+        'README',
+        '.ignore.txt',
+        '.ignore/file.txt',
+        'foo/.ignore.txt',
+        'foo/.ignore/file.txt'
     ])
     def test_add_files_from_theme(self, tdir, ddir):
         config = load_config(docs_dir=ddir, theme={'name': None, 'custom_dir': tdir})