Help User Manual Search Box

PeterJones

The search feature isn’t great; it’s what comes bundled with hugo (the templating system we use for the usermanual). But it is okay for simple searches.

When i try a word, I see the following:

You will notice that the order of the table-of-contents changes – or, actually, all the matching pages come before “Getting started” (which scrolled beyond my screenshot).

All the pages that it brings up before “Getting Started” are pages that the builtin search engine feels matches.

So it’s working right now for me. But maybe 18 hours ago when you tried, there was a brief glitch on the server end.

José Luis Montero Castellanos

@PeterJones
Hello, Thank you for your answer, I apologize if I was not clear.
I am doing the test with the "offline" manual, with the manual installed on my computer.

As I said, it starts an endless loop of the “progresscircle” turning on the right side of the search box, luckily access to the help doesn’t crash.

At the moment I am consulting the hugo-book topic, I understand that it creates a file en.search-data.min.......nnn.json with the contents of the entire manual ~490kb and the flexsearch.min.js script as engine that don’t come with the nppUserManual.zip.

My problem is that I hardly know much about hugo, and I can’t redo the manual. But yes, it is true that the search capacity of the box is quite limited.

Have a good evening…

PeterJones

@José-Luis-Montero-Castellanos said in Help User Manual Search Box:

with the manual installed on my computer

In that case, open index.html in Notepad++, and use Find In Files for a full regex search. Then whatever pages it finds has the text, go to that page in your browser.

José Luis Montero Castellanos

@PeterJones
OK. I already know that method or function and it is a very good alternative, although all the contents are in index.html files (all!) indistinguishable except for the name of the each folder that contains them…

I leave the concern, so that the existence of that search box in the offline user manual makes sense, and thanks again :)

PeterJones

@José-Luis-Montero-Castellanos ,

I would have thought the directory names being different would have been sufficient to distinguish it in your mind, since the Search Results window shows the full path.

I will look into whether there is some option or scripting method of hiding / turning off the search bar when we generate the offline archive (the hugo deployment really expects a live server, so is focused on that; we already had to make use of an external tool to read hugo-deployment to convert it to static HTML). I’ve got some ideas that I’ll play with. But assuming I get it working, it obviously won’t take effect until the next release of the user manual website.

José Luis Montero Castellanos

@PeterJones
No rush, I’m experimenting with hugo, and I’m translating the content of hugo’s book theme, which has a nice demo inside it in a folder called exampleSite.
Hopefully I can help with something. For now I’m investigating how the search script.js and the content.json I mentioned earlier work.

José Luis Montero Castellanos

@PeterJones
Hello:
The following configuration file config.toml allows to adjust the user manual for
local use (localhost). All files go to a single /docs folder with their names intact.

# To build your site for use without a web server (ie browsing
# to public/index.html and then opening the file with your browser) requires:
#
# baseURL = "/" in site configuration
# uglyURLs = true in site configuration
# relativeURLs = true in site configuration
# Removal of all integrity attributes in CSS, JS. Watch themes/congo/layouts/partials/head.html.
# 
# And you'll still run into some details, most notably that Hugo sets the
# home page permalink to "/" instead of "index.html" when uglyURLs is enabled. In our favor in this case.
#
# Not sure it's worth the effort when you can... hugo serve
# Probably. So, you can set unsafe: true. But you can also use the 
# {{< delimiter when including the shortcode in the page. This may or may not be what you want. 
# For config.toml use this:
# [markup.goldmark.renderer]
# unsafe = true


baseURL = '/' 
uglyURLs = true
relativeURLs = true
languageCode = 'es-es'
title = 'Manual de Usuario'
theme = 'book'


# It was used for HTML code to pass, eg. flags and countries
# Needed for mermaid/katex shortcodes
[markup]
[markup.goldmark.renderer]
  unsafe = true

[languages]
#Even if the site is not in English, the following line is required.
[languages.en]

[languages.es]
  languageName = 'Español'
  contentDir = 'content'
  weight = 1

[params]
	# (Optional, default light) Sets color theme: light, dark or AUTO.
	# Theme 'auto' switches between dark and light modes based on browser/os preferences
	BookTheme = 'dark'

	# (Optional, default none) Set the path to a logo for the book. If the logo is
	# /static/logo.png then the path would be 'logo.png'
        # for the notepad++ logo image
	BookLogo = 'logo.gif'

	# (Optional, default true) Enables search function with flexsearch,
	# Index is built on fly, therefore it might slowdown your website.
	# Configuration for indexing can be adjusted in i18n folder per language.
	BookSearch = true

For example: auto-complete·md => auto-complete.html no index.html - also allows passing html code as used for
the flags of the binary-translation·md file or the download box at
the intro file _index·md in the /contents folder).
Despite the use of BookSearch = true the search does not work for me
yet. Finally get the dark mode version of the manual. It can actually be auto depending on the browser configuration.

PeterJones

@José-Luis-Montero-Castellanos ,

I didn’t want to mess around with hugo config/settings. Instead, I just wrote a script which hides the search boxes in the output HTML before creating the zipfile. That’s the way it will be in the next tag/release of the offline User Manual zipfile.

José Luis Montero Castellanos

@PeterJones
My previous comment also refers to the solution of the filenames (each in the zip is index.html instead of their friendly and descriptive name) and their local use. Also the dark and light modes of the user manual.
It would be good that someone take a look at it, and by the way consult it with the pillow. Would it be possible that my modest contribution is of some use?
Have a good day :)

PeterJones

@José-Luis-Montero-Castellanos ,

We aren’t going to be renaming the pages for the online website, because there are too many links from this forum and from the github issues location to specific files in the Online User Manual. And making the offline archive of the User Manual have different page names than the online version would likely create more confusion than it solves.

Unless a significant number of people start asking for a dark version of the offline user manual, I’m not likely to implement building that separately.

However, there is nothing to stop you from grabbing a copy of the usermanual source from github, then use the hugo executable on your own PC to make your own bundle – either an offline version, or just run the hugo server on your PC, since it’s not a cpu-intensive process. (That is: make your own fork, then create a local working copy sync’d to the fork; then every time the master github repo gets updated, you can update your fork with a click on github, and then update your working copy on your PC; if hugo is running live, the changes will take place immediately, otherwise run hugo manually to generate a new version of your local static repo. With your own local copy, you can set the config.toml to whatever you want, to make it look the way you want, without demanding that someone else customize the bundle to your preferences.)

José Luis Montero Castellanos

@PeterJones

It was you who brought up the topic of the “online” manual, not me. Because of this, I had to specify which manual it was…
I don’t think asking! (?) if a “contribution” is usable is a requirement, is it?

Will it be necessary to repeat that none of my posts is a requirement and that many are questions and not “demands” ?

Be courteous as you (or the forum) require of me.
Have an excellent evening! (and it’s not irony).

PeterJones

@José-Luis-Montero-Castellanos ,

It was you who brought up the topic of the “online” manual, not me. Because of this, I had to specify which manual it was…

I am sorry. Since the initial request for, and discussion about, the offline user manual is the only other time other than your clarification where the offline user manual was the focus (that I can remember), my natural reading on any unclarified mention of the user manual is that the online user manual is meant.

Be courteous as you (or the forum) require of me.

The tone of your message felt to me like you had moved beyond a request to a demand. I will take you at your word that you were just making a polite request, and apologize for interpreting it as demand.

Going forward, the offline bundle of the user manual will have the search disabled, because I agreed with you that showing a search bar when the search does nothing is a bad idea for the offline version. Because maintaining a search engine and supporting hugo customizations is not a skill I have nor what I was interested in doing when I volunteered to spearhead the user manual, the easiest solution is to just hide the search in the offline version. And that’s what is happening for the next release.

At this time, the only customization that I will make from the online user manual to the offline bundle will be the disabling of the ineffective search for the offline version.

Your request has been noted, and if future feedback proves that a significant number of others agree with you that the offline bundle needs to be further customized to make it more usable for offline use, then that will be addressed as the feedback warrants.

Until then, I have proposed a viable alternative for you to consider for your own personal use.

José Luis Montero Castellanos

@PeterJones
I tell you that I have the user manual translated into Spanish, and the only thing I need is to solve the search box. That I plan to maintain! if I CAN make it :) I send you a couple of snapshots.
I hope to be able to send it one day… You can see some innovations:

notepad++.png
I managed to organize the flags in columns and alphabetically.

That’s why I do all these queries… But just like others I’m still raw with hugo site.

:-) Good luck in your work :)