diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index fbd5a287..bb0ba228 100644 --- a/docs/user-guide/configuration.md +++ b/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 diff --git a/mkdocs/build.py b/mkdocs/build.py index bda72820..5035daf8 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -28,11 +28,18 @@ def convert_markdown(markdown_source, site_navigation=None, extensions=(), stric """ # Generate the HTML from the markdown source + if isinstance(extensions, dict): + user_extensions = 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) diff --git a/mkdocs/tests/build_tests.py b/mkdocs/tests/build_tests.py index eaadf753..c24c39db 100644 --- a/mkdocs/tests/build_tests.py +++ b/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(""" +

A Header

+ """) + + self.assertEqual(html.strip(), expected_html) \ No newline at end of file