Closed anenadic closed 5 months ago
Hi @anenadic,
Thank you for bringing this up! I've transferred this to the workbench repository since this particular issue is for the workbench as a whole as opposed to the documentation.
The search functionality is currently disabled and I apologise for not flagging it as disabled. I am working on implementing it in an accessible manner, but it may take some time.
The search bar exists because we asked for it during the design of the frontend. The designer added the search bar with a button and the frontend contractors placed it in the lesson, but without functionality behind it because how exactly search results would be displayed was unclear.
That being said, our infrastructure is built on top of {pkgdown} and search functionality does exist in {pkgdown}, as you can see from the {sandpaper} package website, but we do not import any of their JavaScript or CSS the structure of the website is so different.
I thought I opened an issue to add functionality to the search button, but it turns out that I only generated a commit that begins the process with a note about what I found:
While Bootstrap 5 may have search enabled through their forms, it turns out that it's difficult for me to find documentation for this specific task. Moreover, the pkgdown searchbar never had a button associated with the search... and for good reason: the search is dynamic; it does not bring you to a page with your search results; it gives you the search results as a dropdown menu, so you go to your result by clicking "enter". It makes sense! I think we can provide a blank page for search results, but we will need to test out the accessibility for sure.
The steps for me to resolve this are:
pkgdown::build_search()
after all the pages are built in sandpaper:::build_site()
Note about the search functionality, I think the appropriate path is to take the approach of Mozilla Developer N(etwork)? and implement the search field that does two things:
The search page they have looks like this: https://developer.mozilla.org/en-US/search?q=localStorage
@zkamvar I just ran into this as well. Do you plan to work on this soon? If not, it might be better to hide the search box in the meantime to reduce confusion.
Is there currently another smart way of searching within a whole lesson? This is useful for maintainers. Cheers
At the moment, a good way to search the whole lesson is to visit the all in one page, which is located at the bottom of the schedule: https://carpentries.github.io/workbench/transition-guide.html#aio-instructor
The page is always called "aio.html", so you can visit there directly by adding /aio.html
to the URL. For example , this is the all in one page for the workbench tutorial: https://carpentries.github.io/sandpaper-docs/aio.html
And I apologise on my delay with this issue. There are many things that have come up since it was opened -_-
No worries, I'm aware you have a lot of things to think about. The one-page version works perfectly, thank you.
The search box is not selectable. I've tried on multiple SWC lessons, using two different browsers.
@kekoziar, it has not yet been enabled. See https://github.com/carpentries/workbench/issues/8#issuecomment-1150046891 for details.
I have gotten part of the way with https://github.com/carpentries/varnish/pull/86, which you can see the result in my fork of instructor training (https://zkamvar.github.io/instructor-training/), but it's not quite ready as there is still a bit of accessibility testing that needs to happen.
Got it. Thanks. I saw the initial "The search box at the top only provides for search on the actual page and not search across the whole lesson site," and saw that it wasn't enabled, but missed that the box is not selectable. I thought it was only searching partially.
Do you think you can edit your initial answer to say "The search functionality is currently disabled (the search box is not selectable)"?
Given this is a long outstanding issue I wonder if it is possible/worth while to make it much clearer that search doesn't work, or even remove the search bar completely from the display? It isn't at all obvious to me that the search is disabled - I tried clicking many times, checked across browsers, before realising that the field was disabled by checking the code.
I think it would be a better solution to remove the search box until it works. But if this is not possible perhaps it needs to be more obvious it is not implemented yet - by some onscreen text maybe?
Hi @ostephens - the transition to the Workbench has been a lengthy process and this has been on the wayside for a while, but @zkamvar has been making progress in the linked draft PR: https://github.com/carpentries/varnish/pull/86. We'd like to try and get this done by the end of the year, but as we have a lot of other higher priority work, this might not happen. We might be able to fit in a hotfix to more clearly render the search box as disabled, perhaps with a "Disabled" placeholder or some such, but again, I'd have to catch up with Zhian to see if this makes sense given his own thoughts about progress with the draft PR.
How about Select "See all in one page" from menu to search lesson
? It's wordy, but perhaps not everyone knows that page exists, where they can ctrl+f to search at least the lesson.
@froggleston and I have made some updates to Zhian's PR for introducing search functionality and are have reached out to Maintainers to test. The Instructions for Testing Search Bar in Workbench document includes instructions for testing locally and on GitHub. We are asking folks to provide feedback either to this issue or in response to this email on the Maintainers TopicBox by 13 March.
Thanks for tackling this important feature. Here are some of my impressions.
Edited by @ErinBecker to add numbers for easy reference in discussion below.
I've just had a go at testing this locally and on this fork.
It doesn't for me search text / paragraphs. The image below shows me trying to search for the word Parallel (which you can see in the first few lines of text at the bottom) but it finds nothing.
When I do get a match it shows me almost duplicate results for the instructor view vs the learner view vs all in one but doesn't seem to highlight the part I searched for.
If I search for the word Fortran sometimes it lists the code-block title and often when I click on the magnifying glass for this search it will send me straight to a 404 page.
Thank you @quist00 and @astroDimitrios for going through the testing process and providing detailed feedback. This is really helpful.
I have some inkling of how to go about solving issues 1, 2, and 3 raised by @astroDimitrios and possibly issue 5 raised by @quist00. Issues 1-4 and 6-7 raised by @quist00 are pretty far outside of my comfort zone and into some detailed CSS manipulation.
@froggleston - I'm going to see what I can do about addressing @astroDimitrios's 1,2,3 and @quist00's 5 and will post updates here.
Just tested locally (on the instructor training). In addition to what @astroDimitrios brought up:
I did find one other glitch: when results are in the instructor notes page (at least on the instructor training), I get null
in the path (see image below). Relatedly, the learner version seems to populate even for pages in the instructor folder (like the instructor notes.
Thank you @ndporter @astroDimitrios and @quist00 for taking the time to test out this feature and provide detailed feedback. It's really great to see members of the community engaging with the Workbench and helping to make it better!
After banging my head against these issues for a while, it seems to me that using the Algolia Docsearch package to implement search on our lessons (the strategy used in https://github.com/carpentries/varnish/pull/86 and https://github.com/carpentries/sandpaper/pull/495 and to which the feedback above is directed), isn't a good out-of-the-box solution for us, as it doesn't give us the desired look and feel. Our ability to customize Docsearch is also very limited. Pkgdown does also provide a built-in search capability, but according to the docs, "the only available customisation is excluding some paths from the search index." Another option we've considered is embedding a Google search widget, but the time it takes Google to re-index a page depends on a lot of factors, and it may be weeks before changes to the lesson show up in searches.
Given these limitations, we're going to move forward with @kekoziar's suggestion of making the option to search the all in one page more visible. My next update here will include a link to a set of PRs (in progress) for implementing this change.
varnish PR: https://github.com/carpentries/varnish/pull/131 sandpaper PR: TBA
Thanks to @ErinBecker 's awesome efforts, the problematic search box has been replaced by a button that will take you to the All in One page that will facilitate easier searching by the browser's built-in search feature. There were simply too many issues with the Algolia solution that would have taken much longer to fix, so we felt this was the next best thing. Thanks @ErinBecker !
The search box at the top only provides for search on the actual page and not search across the whole lesson site. Is this the intended behaviour?