Add building extra templates

This is similar to extra_css and extra_javascript except it picks up
HTML and XML files and runs them through jinja2 with the global context.
This adds for quite a bit of flexability and allows people to easily add
custom site maps, static and templates htlp.

Fixes #28
Fixes #44

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: MkDocs
-site_url: http://www.mkdocs.org/
+site_url: http://www.mkdocs.org
 site_description: Project documentation with Markdown.
 
 repo_url: https://github.com/mkdocs/mkdocs/

mkdocs/build.py

@@ -91,6 +91,7 @@ def get_global_context(nav, config):
         'nav': nav,
         'base_url': nav.url_context.make_relative('/'),
         'homepage_url': nav.homepage.url,
+        'site_url': config['site_url'],
 
         'extra_css': extra_css,
         'extra_javascript': extra_javascript,
@@ -147,6 +148,17 @@ def get_page_context(page, content, toc, meta, config):
     }
 
 
+def build_sitemap(config, env, site_navigation):
+
+    log.debug("Building sitemap.xml")
+
+    template = env.get_template('sitemap.xml')
+    context = get_global_context(site_navigation, config)
+    output_content = template.render(context)
+    output_path = os.path.join(config['site_dir'], 'sitemap.xml')
+    utils.write_file(output_content.encode('utf-8'), output_path)
+
+
 def build_template(template_name, env, config, site_navigation=None):
 
     log.debug("Building 404.html page")
@@ -215,12 +227,33 @@ def _build_page(page, config, site_navigation, env, dump_json):
     return html_content, table_of_contents, meta
 
 
+def build_extra_templates(extra_templates, config, site_navigation=None):
+
+    log.debug("Building extra_templates page")
+
+    for extra_template in extra_templates:
+
+        input_path = os.path.join(config['docs_dir'], extra_template)
+
+        with open(input_path, 'r', encoding='utf-8') as template_file:
+            template = jinja2.Template(template_file.read())
+
+        if site_navigation is not None:
+            context = get_global_context(site_navigation, config)
+        else:
+            context = {}
+
+        output_content = template.render(context)
+        output_path = os.path.join(config['site_dir'], extra_template)
+        utils.write_file(output_content.encode('utf-8'), output_path)
+
+
 def build_pages(config, dump_json=False):
     """
     Builds all the pages and writes them into the build directory.
     """
     site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
-    loader = jinja2.FileSystemLoader(config['theme_dir'])
+    loader = jinja2.FileSystemLoader(config['theme_dir'] + [config['mkdocs_templates'], ])
     env = jinja2.Environment(loader=loader)
     search_index = search.SearchIndex()
 
@@ -230,6 +263,9 @@ def build_pages(config, dump_json=False):
         log.debug("Search is enabled but the theme doesn't contain a "
                   "search.html file. Assuming the theme implements search "
                   "within a modal.")
+    build_sitemap(config, env, site_navigation)
+
+    build_extra_templates(config['extra_templates'], config, site_navigation)
 
     for page in site_navigation.walk_pages():
 

mkdocs/config.py

@@ -51,6 +51,7 @@
     # Default: List of all .css and .js files in the docs dir.
     'extra_css': None,
     'extra_javascript': None,
+    'extra_templates': None,
 
     # Determine if the site should include the nav and next/prev elements.
     # Default: True if the site has more than one page, False otherwise.
@@ -115,6 +116,7 @@ def validate_config(user_config):
     pages = []
     extra_css = []
     extra_javascript = []
+    extra_templates = []
     for (dirpath, _, filenames) in os.walk(config['docs_dir']):
         for filename in sorted(filenames):
             fullpath = os.path.join(dirpath, filename)
@@ -130,6 +132,8 @@ def validate_config(user_config):
                 extra_css.append(relpath)
             elif utils.is_javascript_file(filename):
                 extra_javascript.append(relpath)
+            elif utils.is_template_file(filename):
+                extra_templates.append(filename)
 
     if config['pages'] is None:
         config['pages'] = pages
@@ -157,8 +161,12 @@ def validate_config(user_config):
     if config['extra_javascript'] is None:
         config['extra_javascript'] = extra_javascript
 
+    if config['extra_templates'] is None:
+        config['extra_templates'] = extra_templates
+
     package_dir = os.path.dirname(__file__)
     theme_dir = [os.path.join(package_dir, 'themes', config['theme']), ]
+    config['mkdocs_templates'] = os.path.join(package_dir, 'templates')
 
     if config['theme_dir'] is not None:
         # If the user has given us a custom theme but not a

mkdocs/nav.py

@@ -6,6 +6,7 @@
 This consists of building a set of interlinked page and header objects.
 """
 
+import datetime
 import logging
 import os
 
@@ -138,6 +139,7 @@ def __init__(self, title, url, path, url_context):
         self.abs_url = url
         self.active = False
         self.url_context = url_context
+        self.update_date = datetime.datetime.now().strftime("%Y-%m-%d")
 
         # Relative paths to the input markdown file and output html file.
         self.input_path = path

mkdocs/templates/sitemap.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+{% for nav_item in nav %}
+    {% if nav_item.children %}
+        {% for nav_item in nav_item.children %}
+    <url>
+     <loc>{{ site_url }}{{ nav_item.abs_url }}</loc>
+     <lastmod>{{nav_item.update_date}}</lastmod>
+     <changefreq>daily</changefreq>
+    </url>
+        {% endfor %}
+    {% else %}
+    <url>
+     <loc>{{ site_url }}{{ nav_item.abs_url }}</loc>
+     <lastmod>{{nav_item.update_date}}</lastmod>
+     <changefreq>daily</changefreq>
+    </url>
+    {% endif %}
+{% endfor %}
+</urlset>

mkdocs/utils.py

@@ -192,6 +192,18 @@ def is_html_file(path):
     ]
 
 
+def is_template_file(path):
+    """
+    Return True if the given file path is an HTML file.
+    """
+    ext = os.path.splitext(path)[1].lower()
+    return ext in [
+        '.html',
+        '.htm',
+        '.xml',
+    ]
+
+
 def create_media_urls(nav, path_list):
     """
     Return a list of URLs that have been processed correctly for inclusion in