Repository: mkdocs/mkdocs

Issue:
Integrating external Documentation
I have a documentation written in mkdocs and an API documentation that gets created automatically from the source code.
I currently just use external links inside my mkdocs to link to my API docu, which works fine. But I can't set the API docu as one of the pages target.
And also mkdocs does not copy the API documentation when doing mkdocs build or mkdocs serve, even though it resides in the docs_dir.

Is there any way to "integrate" external documentation in a mkdocs project? basically all I really need is an "asset dir" where I can dump the external documentation and mkdocs just copies it for me 1:1 when doing build or serve and for mkdocs to allow me to link to these assets.

It works fine with images, but somehow with HTML files mkdocs likes to mess with them (changing them or deleting them entirely).



Discussion:
:+1: 

The problem is [here](https://github.com/mkdocs/mkdocs/blob/ff05df30dd2de8840fb185363afa41a5517a69ef/mkdocs/utils/__init__.py#L147): 

``` python
and not is_html_file(filename)
```

mkdocs is excluding all html files.

Would be great if this could be changed so html documents could be included when serving, building or deploying, I guess via a switch which defaulted to false so current default functionality isn't changed.

I have the same problem with [bokeh.github.io/Bokeh.jl](http://bokeh.github.io/Bokeh.jl/) the plot `.html` files which definitely **are** media files in this context (the whole premise of bokeh is that html can be used as a format for self contained interactive plots) are excluded.

In this case I use 

``` shell
rm -r site/; mkdocs build; cp -r docs/examples/ site/; ghp-import -p site/
```

to ignore mkdocs and deploy the html files to github pages anyway.

Yeah, good point - that is a regression.


Resolving patch:
diff --git a/mkdocs/nav.py b/mkdocs/nav.py
--- a/mkdocs/nav.py
+++ b/mkdocs/nav.py
@@ -217,7 +217,7 @@ def _follow(config_line, url_context, use_dir_urls, header=None, title=None):
         page = _path_to_page(path, title, url_context, use_dir_urls)
 
         if header:
-            page.ancestors = [header]
+            page.ancestors = header.ancestors + [header, ]
             header.children.append(page)
 
         yield page
diff --git a/mkdocs/utils/__init__.py b/mkdocs/utils/__init__.py
--- a/mkdocs/utils/__init__.py
+++ b/mkdocs/utils/__init__.py
@@ -144,7 +144,7 @@ def copy_media_files(from_dir, to_dir):
         dirnames[:] = [d for d in dirnames if not d.startswith('.')]
 
         for filename in filenames:
-            if not is_markdown_file(filename) and not is_html_file(filename):
+            if not is_markdown_file(filename):
                 source_path = os.path.join(source_dir, filename)
                 output_path = os.path.join(output_dir, filename)
                 copy_file(source_path, output_path)


Test patch:
diff --git a/mkdocs/tests/nav_tests.py b/mkdocs/tests/nav_tests.py
--- a/mkdocs/tests/nav_tests.py
+++ b/mkdocs/tests/nav_tests.py
@@ -325,6 +325,9 @@ def test_ancestors(self):
                 {'Running': 'api-guide/running.md'},
                 {'Testing': 'api-guide/testing.md'},
                 {'Debugging': 'api-guide/debugging.md'},
+                {'Advanced': [
+                    {'Part 1': 'api-guide/advanced/part-1.md'},
+                ]},
             ]},
             {'About': [
                 {'Release notes': 'about/release-notes.md'},
@@ -338,12 +341,18 @@ def test_ancestors(self):
             [site_navigation.nav_items[1]],
             [site_navigation.nav_items[1]],
             [site_navigation.nav_items[1]],
+            [site_navigation.nav_items[1],
+                site_navigation.pages[4].ancestors[-1]],
             [site_navigation.nav_items[2]],
             [site_navigation.nav_items[2]],
         )
 
-        for page, expected_ancestor in zip(site_navigation.pages, ancestors):
-            self.assertEqual(page.ancestors, expected_ancestor)
+        self.assertEqual(len(site_navigation.pages), len(ancestors))
+
+        for i, (page, expected_ancestor) in enumerate(
+                zip(site_navigation.pages, ancestors)):
+            self.assertEqual(page.ancestors, expected_ancestor,
+                             "Failed on ancestor test {0}".format(i))
 
     def test_nesting(self):