Ensure nested dot files in themes are ignored.

Also, document how all files within themes are treated by MkDocs.
Fixes mkdocs#1981.

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).

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

mkdocs/structure/files.py

@@ -64,7 +64,8 @@ def css_files(self):
     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:

mkdocs/tests/structure/file_tests.py

@@ -323,7 +323,11 @@ def test_files(self):
         '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})