Merge pull request #435 from waylan/mdx_config

Add support for Markdown extension options.

docs/user-guide/configuration.md

@@ -200,6 +200,22 @@ For example, to enable the [SmartyPants typography extension][smarty], use:
 
     markdown_extensions: [smartypants]
 
+Some extensions provide configuration options of their own. If you would like to set any configuration options, then you can define `markdown_extensions` as a key/value mapping rather than a list. The key must be the name of the extension and the value must be a key/value pair (option name/option value) for the configuration option.
+
+For example, to enable permalinks in the (included) `toc` extension, use:
+
+    markdown_extensions:
+        toc:
+            permalink: True
+
+Add additonal items for each extension. If you have no configuration options to set for a specific extension, then you may leave that extensions options blank:
+
+    markdown_extensions:
+        smartypants:
+        toc:
+            permalink: True
+
+
 **default**: `[]`
 
 [pymdk-extensions]: http://pythonhosted.org/Markdown/extensions/index.html

mkdocs/build.py

@@ -29,11 +29,18 @@ def convert_markdown(markdown_source, site_navigation=None, extensions=(), stric
     """
 
     # Generate the HTML from the markdown source
+    if isinstance(extensions, dict):
+        user_extensions = list(extensions.keys())
+        extension_configs = dict([(k, v) for k, v in extensions.items() if isinstance(v, dict)])
+    else:
+        user_extensions = list(extensions)
+        extension_configs = {}
     builtin_extensions = ['meta', 'toc', 'tables', 'fenced_code']
     mkdocs_extensions = [RelativePathExtension(site_navigation, strict), ]
-    extensions = builtin_extensions + mkdocs_extensions + list(extensions)
+    extensions = set(builtin_extensions + mkdocs_extensions + user_extensions)
     md = markdown.Markdown(
-        extensions=extensions
+        extensions=extensions,
+        extension_configs=extension_configs
     )
     html_content = md.convert(markdown_source)
 

mkdocs/tests/build_tests.py

@@ -320,3 +320,22 @@ class BuildTests(unittest.TestCase):
         self.assertRaises(
             MarkdownNotFound,
             build.convert_markdown, invalid, site_nav, strict=True)
+
+    def test_extension_config(self):
+        """
+        Test that a dictionary of 'markdown_extensions' is recognized as
+        both a list of extensions and a dictionary of extnesion configs.
+        """
+        markdown_extensions = {
+            'toc': {'permalink': True},
+            'meta': None  # This gets ignored as it is an invalid config
+        }
+        html, toc, meta = build.convert_markdown(dedent("""
+        # A Header
+        """), extensions=markdown_extensions)
+
+        expected_html = dedent("""
+        <h1 id="a-header">A Header<a class="headerlink" href="#a-header" title="Permanent link">&para;</a></h1>
+        """)
+
+        self.assertEqual(html.strip(), expected_html)