LoopKit / loopdocs

Loop Docs - https://loopdocs.org/
https://loopdocs.org/
78 stars 145 forks source link

Loopdocs search is too restrictive #284

Closed bjornoleh closed 3 years ago

bjornoleh commented 3 years ago

It would be good if the Loopdocs search gave results for partial hits, not only complete words.

Example: someone who have heard about Zulip will not get results by searching only for "Zulip", they would have to know that it is called Zulipchat in Loopdocs.

https://loopkit.github.io/loopdocs/#stay-in-the-loop

Screenshot_20211030-114814_Chrome

Screenshot_20211030-114831_Chrome

marionbarker commented 3 years ago

I'm happy to make the modifications. Not sure how to do it.

@cfaagaard - Christian - do you have a suggestion?

cfaagaard commented 3 years ago

You can just put a * in front or at the end of your search-word. Or both... Or in the middel 😁

cfaagaard commented 3 years ago

Mkdocs uses lunr, here you can see how you can search: https://lunrjs.com/guides/searching.html

bjornoleh commented 3 years ago

You can just put a * in front or at the end of your search-word. Or both...

Thanks, yes that works. But I don't really expect people to know this. Perhaps it isn't possible to change the search behaviour, but if it is, I think that would make a difference to some.

cfaagaard commented 3 years ago

So you want wildcards as a standard.... Front and back? This will give too many results for a normal search. Maybe a description of how to search in loopdocs would be better.

bjornoleh commented 3 years ago

Perhaps a trailing wildcard would be acceptable? Then you would also see the number of results decrease as the search word is typed out.

In the example above with Zulip, the user might think they had gotten it all wrong when getting no results at first.

Of course a helper page for searching could help, but that will soon be forgotten about I am afraid.

bjornoleh commented 3 years ago

I did a quick test with trailing wildcard. It looks good to me, and I would not mind this as the default behaviour. Both for myself and for anyone who is not familiar with Boolean operators and how to refine a search. If that is possible.

Screenshot_20211031-093240_Chrome

Screenshot_20211031-093318_Chrome

Screenshot_20211031-093347_Chrome

Please notice how the last result include relevant hits that would require two different searches without the trailing wildcard.

cfaagaard commented 3 years ago

Looked into this: mkdocs has decided that this kind of functionality ("changing the default search behaviour") is not going to a part of mkdocs: https://github.com/mkdocs/mkdocs/issues/1914#issuecomment-561179783 They state is should be a theme implementation. Loopdocs use flatly as theme (via mkdocs-bootswatch.): http://mkdocs.github.io/mkdocs-bootswatch/ And flatly do not have this functionality.

So if we want this functionality we have two choices:

  1. we need to implement it our self by customzing the theme and thereby having "the extra work" of maintaining this custom theme when we upgrade mkdocs/flatly (as Marion just did the other day without any problems).
  2. Change to a theme that has this kind of functionality. When I did the markdown-cleanup of loopdocs and the setup for the translation of loopdocs I used the theme "Material" as the current theme "flatly" is old and not maintained. Material has this kind of functionality (in fact trailing wildcard is the default). You can see a old version of loopdocs in action here with that kind of search-functionality: https://loopdocs.github.io/loopdocs/en/

Link til material: https://squidfunk.github.io/mkdocs-material/

bjornoleh commented 3 years ago

Thanks for looking into this!

The newer Material theme looks a bit more up to date and seems more responsive on a phone. The default search here is also how I would have expected it to work.

The overall look is a bit different, and might have some other implications, perhaps requiring some editing of the contents/formatting. If the switch is not too onerous, perhaps it's an idea to change to a theme that is being maintained?

I have very little understand about the total implications though.

cfaagaard commented 3 years ago

I have justed tested the current version of loopdocs (in a fork :-), so no changes in master) with the newest material version. You can see the result here: https://myloopdocstest.github.io/loopdocs/

And it looks like there are some work to be done if we are going to move to this theme.

The fork is here: https://github.com/MyLoopdocsTest/loopdocs

You can see my changes in the commits to run this theme (it is only in requriements.txt and mkdocs.yml)

marionbarker commented 3 years ago

I implemented the changes to requirements.txt and mkdocs.yml from @cfaagaard (as of his commit d18b60e) this morning, in a new branch (new-theme) of my repo and it looks pretty good to me. I don't see any "debris" such as the {width = #} that was in his pages.

(I did the pip install -r requirements.txt before building and I built from my laptop - not the auto-publish on github).

https://marionbarker.github.io/loopdocs/

I'll put this out for comments before implementing this change - it is different but I think in a better way.

cfaagaard commented 3 years ago

Great. I think there is something is going on with the custom css. The icon placement looks wrong. Screenshot_20211031-171108 Maybe remove the whole custom css....

cfaagaard commented 3 years ago

Same page with no custom css Screenshot_20211031-174800

cfaagaard commented 3 years ago

With material there loads of options to configure the site with different functionality: https://squidfunk.github.io/mkdocs-material/

I just implemented a pencil-icon on each page so one can edit the page in github directly. (Just to see how it works) https://myloopdocstest.github.io/loopdocs/

Earlier this year I tested github-issue/comment integration here (scroll down to the bottom of the pages): https://cfaagaard.github.io/MultiLangTest/en/ Here one can comment directly on the page.

marionbarker commented 3 years ago

Thanks for pointing the way Christian.

I'm not going to put all my "playing around" stuff in this conversation. I'm doing incremental commits. I have changed color scheme and added a logo.

The problem you were noticing in the spacing of the icon that got added to the admonitions with this theme was addressed by a change in admonitions.css.

Nightfoxy commented 3 years ago

It's very nice looking! The menu works beautifully on my phone.

Kenny Fox

On Sun, Oct 31, 2021, 11:13 AM Marion Barker @.***> wrote:

Thanks for pointing the way Christian.

I'm not going to put all my "playing around" stuff in this conversation. I'm doing incremental commits. I have changed color scheme and added a logo.

The problem you were noticing in the spacing of the icon that got added to the admonitions with this theme was addressed by a change in admonitions.css.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/LoopKit/loopdocs/issues/284#issuecomment-955767914, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALFNVQN2DPPR3LID4XIVEQLUJWBN3ANCNFSM5HA4PETQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

elnjensen commented 3 years ago

I like it - definitely an improvement in searching. I haven’t played around enough overall to comment on organization/ navigation, but seems fine there too.

Regarding search, is there any way to have a search return an actual page of search results, rather than a transient floating popup? When I’m not sure what page I want, and there are multiple hits in the search result, it’s annoying to have to redo the search every time I want to try a different page to see if it has the info I’m looking for.

marionbarker commented 3 years ago

Yes Eric - right click on the interesting search result and open in new tab. You can work your way down the list.