search

oprypin / mkdocs-section-index

MkDocs plugin to allow clickable sections that lead to an index page
https://oprypin.github.io/mkdocs-section-index
MIT License
77 stars 8 forks source link

Add use-page config option #5

Open jannschu opened 3 years ago

jannschu commented 3 years ago

The option allows to use a different page for the section page instead of the first child.

jannschu commented 3 years ago

Just saw you comments after my last push, I'm on it :)

jannschu commented 3 years ago

I addressed your comments, but I have the feeling that previous_page is now wrong if index_page does not pick the first child. I'll add a test case to be sure.

oprypin commented 3 years ago

Oh wow that's a lot of logic now :( Do you think anyone will actually need the ability to pick index pages from the middle? The option could just require it to be index.md. Doesn't that completely cover your use case?

jannschu commented 3 years ago

Oh wow that's a lot of logic now :( Do you think anyone will actually need the ability to pick index pages from the middle? The option could just require it to be index.md. Doesn't that completely cover your use case?

Actually index.md would be more than enough for me. So I'm fine with restricting it to that, but the logic is basically "fix a doubly linked list".

I'd even argue that if there is no index.md the first page should not become the section page by default since it then depends on alphabetical order but there might be use cases for that.

oprypin commented 3 years ago

I'd even argue that if there is no index.md the first page should not become the section page by default since it then depends on alphabetical order but there might be use cases for that.

Right-- I was thinking that too, but I forgot after seeing your code because it looked totally reasonable :)

Well, if you search for existing usages, people sometimes intentionally use non-index-named pages as the index, but the prerequisite is that their nav is specified manually.

I could make this the default only if the nav is not specified manually, but implementing that is dubious and also I think it's super rare that people just leave their nav alphabetically sorted.

So this should remain just an option.

And sorry but I think we should not keep the logic to reorder the pages. It should still be required to be first.

jannschu commented 3 years ago

Just thougth about the case where a previous plugin might have reordered items such that index.md is no longer first. This could lead to unexpected results if we just check if the first child is index.md with that option. But we could omit a warning in such a case, but actually moving these element in a doubly linked list seems rather clean to me. But it's on you of course, just my final thoughts on this.

By the way if a plugin reorders children after this plugin results are most likely wrong. We could also omit a warning maybe if popular plugins which could do that are behind this plugin.

oprypin commented 3 years ago

The warning is there

https://github.com/oprypin/mkdocs-section-index/blob/7a8b4ac7c87716c2d6a10b672de21d1f5c299bb0/mkdocs_section_index/plugin.py#L53-L56

Though it doesn't detect subtle reorderings. But I think it's not unreasonable to expect the plugins to coexist anyway. Currently all mav reordering plugins I know rewrite the whole nav.

solonovamax commented 3 years ago

What's the status on this? Because it fixes #6, which is a very annoying issue for me.

oprypin commented 3 years ago

Hmm the status is that I'm a bad human. I didn't follow up on this. The feature is needed, but I wasn't sure how exactly it should look like.