Does not recognize underline (=) notation as heading 1.

[crivetimihai]

It does not recognize underline (=) notation as heading 1.

[timvink]

Hi @crivetimihai ,

Thanks for reporting. I'm having trouble reproducing this issue. Can you give a specific example?

[crivetimihai]

Hi Tim,

Thanks for the reply. I think the plugin is very cool - I love the idea. But I'm having issues getting it to work with different types of markdown notations. Example:

Issue 1: support for underscore headings

The headings are only detected if you're using the # Heading 1 style of markdown notation, but not the Heading 1 with ============ below.

Is this using a markdown parser or regexp to detect headings?

Reproducing the issue:

requirements.txt

mkdocs
mkdocs-enumerate-headings-plugin

mkdocs.yml

nav:
  - 'Introduction': 'index.md'

site_name: test

plugins:
    - search
    - enumerate-headings

docs/index.md

Heading 1 with underlines
=========

# Heading 1 with hash

Heading 2 with underline
---------

Test

Heading 2 with underline
---------

# Heading 2 with hash

Test

# Heading 3

Test

python -m venv .python37
source .python37/bin/activate
mkdocs serve

Output HTML:

Heading 1 with underlines
1. Heading 1 with hash
Heading 2 with underline
Test

Heading 2 with underline
2. Heading 2 with hash
qsadas

3. Heading 3

Issue 2: Regexp breaks when there is no space after the #

#heading-break-regexp
AssertionError: Line '#heading-break-regexp' does not match regex

This can be fixed by adding a space: # heading-break-regexp

[timvink]

I think the plugin is very cool - I love the idea.

Thanks! I think this plugin is actually the coolest & most useful MkDocs plugin I've built -- but not the one that's picking up a lot of traction 🤷‍♂️

I'm having issues getting it to work with different types of markdown notations
Issue 1: support for underscore headings

Thanks for the clarification. I only now learned that there are two styles of markdown headings that mkdocs supports (through python-markdown): atx and setext (see reference).

The setext implementation has all kinds of specifics that I don't want to replicate. Perhaps I took the wrong approach with the first version of this plugin: I should have let python-markdown do the parsing for me and use the HTML to retrieve headings. Long story short: no support for setext style headings for now. Will try to include support in a next major version.

Issue 2: Regexp breaks when there is no space after the #

Proper behaviour should be to ignore, not through an error, as it is not a valid heading. I will look into this, thanks!

[crivetimihai]

I really like the idea (enumerate headings). Form word templates to DITA and LaTeX templates - I use enumeration in all my documents. It even makes sense if you use pdf-export with mkdocs.

Thanks! I think this plugin is actually the coolest & most useful MkDocs plugin I've built -- but not the one that's picking up a lot of traction man_shrugging

Haha, for sure, though I think mkdocs-table-reader-plugin comes close!! I just realized you're the author for git-authors and git-revision-date-localized - which, along with awesome-pages makes mkdocs.. well.. awesome! Thanks for sharing :-).

From an implementation perspective, is there a way to tie into whatever mkdocs is doing and piggy back on their parser / extend some classes or something? Or is there some super secret Jinja technique you could be using?

Thinking python-markdown is a better approach than regexp, for sure, but I'm still not clear on how this will behave when you have other plugins.
(just brainstorming..)

[timvink]

I researched this more and rewrote large parts of this plugin. I now have a working version that processes the HTML output instead of the markdown input. Both issues have been addressed already, but I need to expand the unit tests further before releasing.

[timvink]

@crivetimihai I just released v0.2 to address both issues. Thanks for the report, I wouldn't have found this better approach without it.

[flywire]

I will test some more but initially:
ERROR - Error reading page 'index.md': Line '#include "my_dialog .h"' does not match regex

Error only occurs when plugin loaded.

Given second character is not a space I'd expect it to pass through.

[timvink]

I suspect you're still running v0.2, try:

pip install --upgrade --force-reinstall mkdocs-enumerate-headings-plugin

[flywire]

Yes running v0.2 on Win10:
input:

• #include <QApplication>
#include "my_dialog .h"
Read the headers of, respectively, the Qt QApplication class

output:

[timvink]

Is that the output you expected? If enumerate-headings is messing up the output (and disabling it repairs it), then please open a new issue and also include your mkdocs.yml setup.

[flywire]

I understood #11 (comment) that headings would not occur without a space following #:

Issue 2: Regexp breaks when there is no space after the #

mkdocs.yml

[timvink]

Yes, the error should not occur. The heading creation does occur. Note that this default behaviour of MkDocs. Your example index.md:

• #include <QApplication>
#include "my_dialog .h"
Read the headers of, respectively, the Qt QApplication class

with mkdocs.yml:

site_name: test plugin
use_directory_urls: false

plugins:
    - search

Renders as:

And with enumerate-headings enabled, it properly adds the enumeration:

[crivetimihai]

Hi, probably another thing to consider: not all pages have a Heading 1. For example, you can leave that out, and Heading 1 automatically becomes the page name.

If that's the case, then this will return:

    return "#" + self.heading.get("id")
TypeError: can only concatenate str (not "NoneType") to str

To make it fully compatible with mkdocs, Heading 1 should also be derived from the page title if there is none present in the document. The Page Title (1. Heading 1) in the document can be derived either from nav, the file name OR the first markdown # or = title in the page.

I personally use awesome-pages with NO nav, and no heading 1 in the markdown, naming my pages My-Page-Name.md so it automatically becomes: My Page Name.

[timvink]

Ah! I have unit tests for pages without headings, and unit tests for compatiblity with awesome-pages, but not this case. I opened #18 and will probably look into it next weekend.