rylon / mkdocs-nav-enhancements

WIP plugin for working with titles of pages in MkDocs.

MkDocs Nav Enhancements

This is a small plugin for the excellent MkDocs project which makes some enhancements to the navigation.

Features

Enhanced titles

By default, MkDocs looks for a level 1 atx-style header found at the top of the document and uses that for the page title.

If you are dealing with documentation from third-party sources you may find that some of them start their titles at level 2 (possibly for aesthetic reasons), or use setext-style headers instead.

This plugin will try to help by looking through each Markdown document and using the following rules to detect a page title instead:

• Use the first atx-style header found in the document at any level between 1 to 6, which is any line beginning with between 1 to 6 '#' characters.

• Or use the first setext-style header, which is any line where the line immediately after contains only '=' or '-' characters, effectively 'underlining' the line.

It will also remove any additional markup that is found in the title, such as image or link tags, which would otherwise be rendered as string literals in the generated HTML.

Reduced folders

In order to de-clutter the navigation, the plugin looks for any sections containing only one page, and tries to collapse that page up a level into its parent. This helps deal with navigation bars filled with single-page folders to keep things looking tidy.

Usage

Install the plugin:

pip install mkdocs-nav-enhancements

Add the plugin to your mkdocs.yml MkDocs configuration file:

plugins:
  - mkdocs-nav-enhancements

Known issues

When changing the page title, or collapsing single-page folders, this can sometimes result in the effective page title being quite different. Currently this plugin does not re-sort the nav bar alphabetically when this happens.

A second issue is that these options are not independently controllable, at least not in the first version; it's all or nothing for now!

Contributing

Source code is hosted at GitHub.

Please report issues and feature requests on GitHub Issues.

Pull Requests are also welcome!

mkdocs-nav-enhancements's Issues

If markdown is empty, plugin crashes the entire flow

Line 104 makes the entire flow crash if one of the included markdown files in config's nav is empty:

mkdocs-nav-enhancements/mkdocs_nav_enhancements/__init__.py

Line 104 in d7ca8cd

next_line_chars = set( lines[ line_number + 1 ].strip() )

Here's the error, for reference:

Traceback (most recent call last):
  File "/Users/kallewesterling/opt/anaconda3/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs/__main__.py", line 133, in serve_command
    serve.serve(
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 141, in serve
    config = builder()
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 136, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs/commands/build.py", line 167, in _populate_page
    page.markdown = config['plugins'].run_event(
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs_nav_enhancements/__init__.py", line 118, in on_page_markdown
    new_title = self._look_for_title_in_markdown(markdown)
  File "/Users/kallewesterling/opt/anaconda3/lib/python3.8/site-packages/mkdocs_nav_enhancements/__init__.py", line 104, in _look_for_title_in_markdown
    next_line_chars = set( lines[ line_number + 1 ].strip() )
IndexError: list index out of range

I think a solution would be, maybe to wrap this in a try and except IndexError where the exception would just continue in the wrapping for loop (on line 74).