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
Search in 0.17.0 is incompatible with third-party themes #1316
Comments
I'm not sure why its not work for you as I haven't taken a look at your source, but here are some notes about the changes we made to the builtin themes which may help. Of course, search works for both of the included themes, each of which works differently. The mkdocs theme uses a modal box rather than a In the readthedocs theme, the only change we needed to make to the Additionally, we needed to make a couple changes to To be clear, I haven't really looked at any third party themes with consideration to how they might interact with plugins. If there is anything we should be doing different to make things easier, let us know. That's part of the reason we released the Plugin API in 0.17. We still have time to make changes before 1.0. |
One additional note: I only did the minimum necessary to get search working as a plugin. The original plan was to completely refactor the search plugin to address all of the issues listed in the search refactor project. But that didn't happen yet. If it had, search would be a completely new thing and the changes would probably be more easily justified. However, now that we have everything controlled by the plugin, the future refactor should have less impact on themes. In other words, if you make the changes to work with this, you won't need to make many (if any) adjustments in the future when the search refactor happens. |
... and now that I have actually read your output, I see this:
As I pointed out above, the search index would now be at |
Thanks for your extensive answer. The warning about the missing |
The search plugin seems to automatically include two files: <script src="./search/require.js"></script>
<script src="./search/search.js"></script> How can I disable this? Material provides an own search logic that doesn't need the code. |
Its not new. Perhaps it was only displayed with the
It is. As the release notes explain:
And as explained in the configuration docs:
You have two options: (1) provide your own replacement plugin or (2) provide your own replacement files in the theme. I'm assuming you would want to use option 2, although option 1 would be as simple as a subclass which re-implemented step 1 below. Perhaps it would help to explain how the search plugin works. The code is here and its not very complicated. But I'll break it down into the three basic steps:
|
Thanks for your long answer and excuse me not reading the docs properly, mainly due to a lack of time on my side. However, I have some remaining questions:
Option 1 increases potential errors on the user side. I would have to instruct the user to always install my custom search plugin with the theme. That's not practical. Can the theme itself provide a plugin or do I have to register a whole new project in pip? If the later is the case, this would really, really complicate everything for Material and degrade user experience. Besides the original MkDocs theme and the ReadTheDocs theme, Material seems to be one of the most used, so this may impact a lot of users. Option 2 is not really an option, because Material implements the search logic itself. Material only depends on the I have to pin Material to 0.16.3 until this is resolved, because now it breaks one way or the other way. However, I have no idea how to tackle this in a practical way which is transparent to the user. The last part is really important because a lot of build environments will break with option 1 and option 2 always shows errors of missing files in the console. |
There isn't any reason why this couldn't work (sort of). Both themes and plugins are simply Python modules with an entry_point to point to them. You can have more than one entry_point in a package (the MkDocs package includes two themes and one plugin right now). Just include each in a separate subdir and point the entry_points appropriately. The one disadvantage is that the user still needs to list both in the config manually. You could have a plugin which changes the
As a reminder, the existing search functionality is expected to undergo a complete refactor prior to the next release (primarily the JavaScript end of things). For example, I expect that require.js will no longer be used. If a third-party theme is providing its own search logic, why can't that logic be contained in a file at Another solution just occurred to me. Plugins can have their own config options. The current plugin has none because it is simply replicating the existing behavior (which had no configuration options). However, we could add a config option to the plugin which only created the plugins:
- search:
index_only: true Would that work for you? I realize that would still break for existing users until they updated their configs, but it would give you what you actually want going forward. And the "fix" for existing users would be to add that one setting. As an aside, I had not realized that you (or any third-party theme, for that matter) were implementing your own search logic. Knowing that would likely have informed some of the decisions that were made. When discussing the current solutions for both the Plugin API and the Theme Customization feature, I remember begin surprised that no theme devs chimed in. PRs were posted and sat for days waiting for feedback before being merged. The silence was interpreted as no objections. Perhaps I was wrong in making that assumption. That's a significant factor in releasing 0.17 rather than going straight to 1.0. We're not locked in yet. |
Perhaps even better, We could make the default dependent on a theme option. That way, the default behavior would depend on the theme. For example, Material's search_index_only: true Whereas the search_index_only: false We could even define a setting for search modal vs. a dedicated search page, which would control whether |
Short answer (long answer later): The search-index only solution would be perfect. When this is implemented, I can fix all incompatibilities and release Material 2.0 which requires MkDocs 0.17. Also the EDIT: thinking about it again, it would be better to have a solution that a theme defines plugin dependencies and default configuration. I know, there's no option for that, but then the nice setup instructions of "just add |
We have the default config (for theme specific stuff), but I'm not sure how the plugin dependencies would work. Would the theme define its own The one exception is that a Plugin could define its own "theme specific" config options. That way, the theme can inform a plugin which way it expects the plugin to work. To demonstrate, consider the There are currently two ways to have a My proposed solution is to add another theme setting which is specific to the search plugin. When |
I just pushed a proposed fix to #1322. See the documentation for an explanation of the proposed changes. Actually, I noticed while working on this that the "search" documentation was outdated and wrong in some cases. Its clear I didn't give enough thought to that side of things when I was working on the Plugin API. I hadn't made a single change to that part of the documentation, In retrospect, I recall thinking as some point i would come back to that after working out some other issues with the Plugin API. Apparently I never did. |
So from what I see in the docs and your notes I could now provide a plugins:
- search:
search_index_only: true
include_search_page: false Is that correct? Also, what are the default options for those attributes? And for the user, configuration would be done with just defining |
Reading the Python code in your PR, I assume I wouldn't have to provide anything at all. Even better, but I would set it explicitly in Material, so it doesn't break if at some point in the future the default values are changed. |
You almost have it. You cannot (and I expect never will be able to) define a plugin in search_index_only: true
include_search_page: false The user would still need to have the plugin enabled in their MkDocs config. Of course, it is enable by default, but the user could disable it and any theme MUST account for that. Also as a warning, a user COULD override the defaults you set in her theme:
name: material
search_index_only: false
include_search_page: true Technically there are no defaults. If they are not defined by the theme (in its |
By the way, the new settings are not "plugin" settings (you cannot define them under the plugin in |
Okay, got it. That would solve the problems with 0.17! Thank you very much for your time, patienc and work. When can we expect 0.17.1? Are there any other issues that need to be solved before? |
I expect 0.17.1 will be out before next week. There are a couple other possible issues, but they seem very minor. |
Fixed in #1322. |
Any update on 0.17.1? |
Unfortunately, I ran out of time on Friday. I'm guessing Monday or Tuesday. |
0.17.1 has been released. |
Well, in my case, there's no "mkdocs" dir under site/, so I copied and pasted the mkdocs folder from my prious site, now the search function is back. |
@breezedu it sounds like you are using a theme which has not been updated for 0.17. |
Also include search settings into instructions for using custom_dir, since theme's mkdocs_theme.yml is ignored in that case (see mkdocs/mkdocs#1316 (comment))
The search page needs to be included to allow showing 'all results'. In documentation, what used to be 'theme_dir' is now 'theme.custom_dir'. Also include search settings into instructions for using custom_dir, since theme's mkdocs_theme.yml is ignored in that case (see mkdocs/mkdocs#1316 (comment))
Firstly, congratulations on version 0.17. Really nice to see MkDocs is evolving. I read about the new plugin system and tried to upgrade to MkDocs 0.17. I also added this to my
mkdocs.yml
:However, the index doesn't seem to be generated and MkDocs is complaining about a
search.html
not being present. Material defines thesearch.html
as a partial, as it's part of the main theme.Any directions?
The text was updated successfully, but these errors were encountered: