SEARCH: Improve by adding DocSearch annotation markup

[HenrikBengtsson]

The new search box relies on DocSearch, which is a free service provided by Algolia. They crawl the website once every 24 hours. The search UI is based on JavaScript.

I've used it for a while for the docs of my R packages - docs that by nature are very well structured, e.g. https://future.futureverse.org/. The Wynton HPC website is less structured (in the sense of sections, tags, title, concepts, etc.), which is why the DocSearch fail to pick up certain things, e.g. the different software names in the modules, e.g. a search for bamtools comes up empty. In order to improve on this, I need to improve on the default search "selectors". We might also have to introduce additional meta tags in our documentation.

[HenrikBengtsson]

Punting on this until we migrate to Quarto. When that's done, we'll get search indexing built-in, which removes the need for DocSearch and tweaking it.

[murashka-ucsf]

It's been decided to migrate to Quarto?

Do I have it correct that Quarto would be used to render the Markdown and Jekyll still to translate that to HTML?

[HenrikBengtsson]

It's been decided to migrate to Quarto?

I made the decision :p

More seriously, I'm using it to create various Quarto Books (HTML and PDF). It's awesome and the new generation of content creation. BTW, I highly recommend for the sysadmin book(s). People on social media speaks highly of it too and use it for books, websites, and blogs.

Do I have it correct that Quarto would be used to render the Markdown and Jekyll still to translate that to HTML?

Yes, it'll be basically as before, with more power. It's only some of the Liquid-embedded code (i.e. {{ ... }}) that needs to be tweaked.

It'll be a while before we migrate the Wynton site, though. I'll upgrade our https://cbi.ucsf.edu/ first and see what I learn from doing that.

[HenrikBengtsson]

Do I have it correct that Quarto would be used to render the Markdown and Jekyll still to translate that to HTML?

Sorry, I missed the Jekyll part. Quarto does not use Jekyll; it uses its own site generator and then pandoc to convert Markdown to HTML (and PDF and ePub, if wanted).

[murashka-ucsf]

I see. Quarto looks interesting enough, and Pandoc is cool. Pandoc converts anything to anything as far as documents go as far as I can tell.

I'm just worried about creating barriers to other people making edits to the website since I haven't even had time to look at more than the Quarto website and Wikipedia entry.

It'll still just output markdown files to Github though I imaging.

What about the site styling though. Jekyll / Hugo and other static site generators use themes of course, what's Quarto do for site styling, layout, macros, menus, etc?

[HenrikBengtsson]

Making it as simple as possible for any user to edit/tweak a webpage is top priority. I don't think we can make it easier than using Markdown.

What about the site styling though.

That should be basically equally easy. I expect a single webpage template and CSS on top of that. I'll find out, but I don't think it'll be an issue. The people behind Quarto have years of experience and expertise in this field (e.g. Distill, Rmarkdown, bookdown, blogdown, ...) where that target both rookie users and advanced users.

[murashka-ucsf]

I think whether Markdown is easier for most people is debatable.

Having run departmental CMS systems for years, I've found users far more likely to edit content on sites that have a simple login and WYSIWYG content editor than anything requiring touching html/css/sass/php or markdown files on a file system and having those changes pushed out by some batch process or any process beyond a simple button click.

Actually MkDocs I've found reasonable but mainly because I've used it before and it seems relatively wide-spread.

That said, I'm not even remotely suggesting running a heavyweight CMS.

It's more that I'm assuming nobody else on Wynton has any familiarity with Quarto and I don't even have a notion of whether Quarto is better for documents or for say a web site that might contain more dynamic data.

I'm not even suggesting Quarto isn't a good idea, it just seems out of left field (which just about anything originating in the R ecosystem might be for anyone not knee deep in it).

[murashka-ucsf]

For that matter hasn't RStudio just recently changed it's name to Posit? Or is the software still referred to as RStudio but the company behind it is Posit?

[HenrikBengtsson]

The software is still referred to as RStudio

[HenrikBengtsson]

I strongly believe that WYSIWYG editors wreak havoc when it comes to structured information. You need structure for search, cross referencing, generations of table of content, content validation, modularization, templating, styling, diff:ing, version control, etc. Just look at MS Word documents - I can count the ones I've seen over years that are properly structured on one hand. Don't even get me started with WYSIWYG emails.

Look and style should not be left to the writer/editor. All the person should have to worry about is content and structure (sections and subsections). I think Markdown managed to strike a decent balance on readability, simplicity, and structure. It's also the de facto standard out there.

[HenrikBengtsson]

FYI, I'll try to explore MkDocs, before making a final decision.