Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow specifying Markdown config: extensions, tab_length #15

Merged
merged 1 commit into from
Jan 6, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
23 changes: 23 additions & 0 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
8 changes: 7 additions & 1 deletion mkdocs_literate_nav/parser.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)):
Expand Down
17 changes: 15 additions & 2 deletions mkdocs_literate_nav/plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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("."):
Expand Down