From 908f7b24afe0890a9cedf0727ec925ccadb5fbdc Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Thu, 29 Dec 2022 22:18:37 +0100 Subject: [PATCH] Allow specifying Markdown config: extensions, tab_length --- README.md | 4 ++++ docs/reference.md | 23 +++++++++++++++++++++++ mkdocs_literate_nav/parser.py | 8 +++++++- mkdocs_literate_nav/plugin.py | 17 +++++++++++++++-- 4 files changed, 49 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b6ce43d..e790311 100644 --- a/README.md +++ b/README.md @@ -396,6 +396,10 @@ Let's say you need the ability to infer nav for a sub-directory, but are unhappy [See an example that generates both the files and the navigation covering them](https://github.com/mkdocstrings/mkdocstrings/blob/5802b1ef5ad9bf6077974f777bd55f32ce2bc219/docs/gen_doc_stubs.py#L25). +#### Indent lists by 2 spaces, not 4 + +Configure it through [tab_length](https://oprypin.github.io/mkdocs-literate-nav/reference.html#wildcards) or [markdown_extensions](https://oprypin.github.io/mkdocs-literate-nav/reference.html#wildcards) + #### Migrating from GitBook? It might be very easy! Just beware of the stricter Markdown parser; it will *not* accept 2-space indentation for sub-lists. diff --git a/docs/reference.md b/docs/reference.md index 5babecf..354793b 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -90,6 +90,7 @@ Wildcards (items without a title that have an asterisk in them) get replaced by - literate-nav: nav_file: SUMMARY.md implicit_index: false + tab_length: 4 ``` ### Config @@ -112,6 +113,28 @@ If a directory has a file named [`index.md` or `README.md`](https://www.mkdocs.o This is important when using directory cross-linking, which otherwise makes it impossible to specify a *[section-index][]* page for a subdirectory. +#### `tab_length` + +*integer, default `4`* + +By default (like in MkDocs), lists need to be indented by 4 spaces. The more modern style is 2 spaces, though. + +You can change the indentation just for the extension, but that will not affect MkDocs' rendering. If you want to change both at once, install [mdx_truly_sane_lists](https://github.com/radude/mdx_truly_sane_lists) and use it through `markdown_extensions`, instead of this option. See example below. + +#### `markdown_extensions` + +*list of mappings, [same as MkDocs](https://www.mkdocs.org/user-guide/configuration/#markdown_extensions)* + +!!! example "mkdocs.yml" + ```yaml + plugins: + - literate-nav: + markdown_extensions: + - mdx_truly_sane_lists + + markdown_extensions: + - mdx_truly_sane_lists + ``` [mkdocs-nav]: https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir diff --git a/mkdocs_literate_nav/parser.py b/mkdocs_literate_nav/parser.py index db46c87..2b72d2c 100644 --- a/mkdocs_literate_nav/parser.py +++ b/mkdocs_literate_nav/parser.py @@ -38,10 +38,12 @@ def __init__( get_nav_for_dir: Callable[[str], tuple[str, str] | None], globber, implicit_index: bool = False, + markdown_config: dict | None = None, ): self.get_nav_for_dir = get_nav_for_dir self.globber = globber self.implicit_index = implicit_index + self._markdown_config = markdown_config or {} self.seen_items: set[str] = set() self._warn = functools.lru_cache()(log.warning) @@ -51,7 +53,11 @@ def markdown_to_nav(self, roots: tuple[str, ...] = (".",)) -> Nav: dir_nav = self.get_nav_for_dir(root) if dir_nav: nav_file_name, md = dir_nav - markdown.markdown(md, extensions=[ext]) + markdown_config = dict( + self._markdown_config, + extensions=[ext, *self._markdown_config.get("extensions", ())], + ) + markdown.markdown(md, **markdown_config) if ext.nav is not None: self_path = posixpath.normpath(posixpath.join(root, nav_file_name)) if not (self.implicit_index and self_path == self.globber.find_index(root)): diff --git a/mkdocs_literate_nav/plugin.py b/mkdocs_literate_nav/plugin.py index 092c6d8..52e345e 100644 --- a/mkdocs_literate_nav/plugin.py +++ b/mkdocs_literate_nav/plugin.py @@ -29,6 +29,8 @@ class _PluginConfig: nav_file = mkdocs.config.config_options.Type(str, default="SUMMARY.md") implicit_index = mkdocs.config.config_options.Type(bool, default=False) + markdown_extensions = mkdocs.config.config_options.MarkdownExtensions() + tab_length = mkdocs.config.config_options.Type(int, default=4) class LiterateNavPlugin(mkdocs.plugins.BasePlugin): @@ -45,6 +47,11 @@ def on_files(self, files: mkdocs.structure.files.Files, config: mkdocs.config.Co files, nav_file_name=self.config["nav_file"], implicit_index=self.config["implicit_index"], + markdown_config=dict( + extensions=self.config["markdown_extensions"], + extension_configs=self.config["mdx_configs"], + tab_length=self.config["tab_length"], + ), ) self._files = files @@ -62,7 +69,11 @@ def on_nav( def resolve_directories_in_nav( - nav_data, files: mkdocs.structure.files.Files, nav_file_name: str, implicit_index: bool + nav_data, + files: mkdocs.structure.files.Files, + nav_file_name: str, + implicit_index: bool, + markdown_config: dict | None = None, ): """Walk through a standard MkDocs nav config and replace `directory/` references. @@ -86,7 +97,9 @@ def get_nav_for_dir(path: str) -> tuple[str, str] | None: return nav_file_name, f.read() globber = MkDocsGlobber(files) - nav_parser = parser.NavParser(get_nav_for_dir, globber, implicit_index=implicit_index) + nav_parser = parser.NavParser( + get_nav_for_dir, globber, implicit_index=implicit_index, markdown_config=markdown_config + ) result = None if not nav_data or get_nav_for_dir("."):