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
74 stars 7 forks source link

Does not work with local theme #4

Open ghost opened 3 years ago

ghost commented 3 years ago

If I add a local theme or overrides:

https://squidfunk.github.io/mkdocs-material/customization/#setup-and-theme-structure

The headings are not clickable anymore.

oprypin commented 3 years ago

Yeah, then you're discarding the patching that this plugin does.

The patching is needed here because this theme's author refused to include the edits into the theme itself.

You need to name your local theme "material" and/or use the patched content as the base for your edits, rather than the original content. As of right now, the patched files are as follows:

https://github.com/oprypin/mkdocs-section-index/blob/145ce693fa86d950e602fc8f6eab1ea29c8be236/tests/rewrites/material-tabs-item-2.yml#L32-L59 https://github.com/oprypin/mkdocs-section-index/blob/145ce693fa86d950e602fc8f6eab1ea29c8be236/tests/rewrites/material-nav-item-3.yml#L71-L152

And separately regarding local theme: if you're actually making an entirely new theme, then just implement it with support for this plugin, as per instructions: https://github.com/oprypin/mkdocs-section-index#implementation

ghost commented 3 years ago

Thanks, that explains it.

And I'm sorry, but I know next to nothing abou jinja, just wanted to use material and override some parts of it.

I tried to understand what you meant and assumed you meant I should replace

tabs-item.html and nav-item.html in the partial folders in the custom folder, and it will override?

Or do I need to copy the entire material theme and replace files in that and use it?

oprypin commented 3 years ago

Follow whatever instructions you've been following, and if during that you encounter a part "copy the file from the theme, then edit it", instead copy it from the snippets I pasted here in the issue. (applies only to tab-item and nav-item).

Let me know if this is still unclear

ghost commented 3 years ago

Thanks, I didn't choose my nick by accident you know. I will try harder...

I was asking since when I tried to do it beore I got build error "Failed to adapt the theme file 'theme/material/partials/nav-item.html'. This is likely a bug in mkdocs-section-index, and things won't work as expected."

So was trying to understand where to put things so it would work.

No need to reply, just letting you know.

oprypin commented 3 years ago

Hmm I've never actually tried the overriding workflow, there are probably some rough edges. (and from what you're saying, possibly no way to silence that error message)