Add search to docs

[aidanreilly]

A site specific search would be a very useful addition to the monome docs.

[tehn]

@simonvanderveldt did a nice search on his jekyll site:

http://rennsportengineering.com/wiki/ https://github.com/rennsportengineering/wiki

[simonvanderveldt]

Yeah, it's slightly problematic in that GitHub Pages/Jekyll are static sites, meaning there's no backed you can send search queries to.

So pretty much the only thing you can do is create an index which contains all the data/things you want to search for, probably in a JSON file, and then use that as the "backend" for the search.

This does mean that all this data needs to be downloaded/read by the browser so while it works for small sites it definitely isn't a good fit for larger ones. I don't know where the docs fall in this, we could try it out.

The site linked uses https://github.com/olivernn/lunr.js for the search engine.

[aidanreilly]

I went ahead and forked the docs repo to play around with an mkdocs build. You can have a poke around that output here: https://aidanreilly.github.io/docs-test/ the actual markdown content is unchanged, so some of the page links are broken, however, the left hand 'site nav', and right hand 'page nav' should be working OK, or enough to get a feel for how mkdocs works. The search also works. Site search is powered by lunr.js

The site theme is material for mkdocs. https://squidfunk.github.io/mkdocs-material/

I'm not a developer, so further tinkering would be beyond me, not that I have the time either tbh. custom css is possible of course.

There are some other features which come out of the box with this which are really nice too.

1. edit links on every page could bring you to the source in github. Nice for collaborative edits and related updates work.
2. disqus plugin could also be enabled - this could draw users in with easy comments features on every page. Maybe there is a discourse plugin that could be leveraged for comments? that could be cool.

https://www.mkdocs.org/user-guide/configuration/

Anyway. I'll leave this up for a day or two, let me know what your thoughts are. If you're planning a custom route for the look and feel, or just further development on the current jekyll build that's cool.

:)

Off to bed now...

[tehn]

this is very impressive! i wasn't aware of mkdocs, thank you

i could see this working well with some styling and removal of some features.

wondering if it's possible to represent more of the doc hierarchy on the left (basically sub-files) or perhaps it's better design to have the ToC be for digging in.

curious to hear more feedback from others.

[simonvanderveldt]

I've worked with mkdocs about 1.5 years ago, it was OKish back then, we dropped it in the end. Don't really remember the details.

What would be the advantage vs the current setup?

Anyway, it would mean a CI setup would need to be added to build the site automatically since it's not Jekyll. If you like the styling it's probably easier to just use readthedocs and if you want custom styling and to fit it into the monome site I'd expect the current solution to be be easier.

[aidanreilly]

Hmm. Hadn't considered that CI would be required for mkdocs. From a technical standpoint, I'm not sure there is a benefit tbh. The out of the box navigation and search is what appeals to me. Perhaps just developing the nav and search for the jekyll build is the best approach as you say. There is a tech doc theme for jekyll here which seems nice:

https://github.com/pmarsceill/just-the-docs

[tehn]

ah. yes we need a jekyll solution--- i really don't want to add another CI layer.

just-the-docs looks good and would be a simple starting point for styling

[aidanreilly]

i'll spin that up and see what it looks like.

[simonvanderveldt]

@tehn Do you have any ideas/direction regarding styling of the docs? How much should it match with the monome site?

[aidanreilly]

https://aidanreilly.github.io/docs/ basic just-the-docs jekyll template. Search seems ok - lunr.js. A bit fiddly on mobile.

I noticed topics don't have titles, this might be an issue for proper navigation. The TOC also needs some work i think.

[tehn]

@aidanreilly looks like a good start! the search works well.

interesting that there are a bunch of links missing on the sidebar. and there's no ToC?

@simonvanderveldt re: styling. it should follow the monome site (colors, face, etc) i think something close to the TT docs layout makes sense: https://monome.org/docs/modular/teletype/manual/

makethedocs had really good table format styling

[simonvanderveldt]

@simonvanderveldt re: styling. it should follow the monome site (colors, face, etc) i think something close to the TT docs layout makes sense: https://monome.org/docs/modular/teletype/manual/

That looks pretty nice and very legible! It seems to be a HTML page generated using pandoc. i guess we could look into getting the basic styling and sidebar layout and transplanting that on top of just-the-docs?

[tehn]

styling/formatting is easy to change as long as the core functionality we want is there (sidebar pages, ToC, search)

[aidanreilly]

Re: page titles - this particular theme requires a title in the header for navigation. There’s probably an easy enough search and replace to duplicate the first occurrence h1 titles into the header for *.md. Child topics navigation would also need to be done.

There may be a Jekyll plug-in to make this easier, I’m not sure.

Aidan

On 16 Oct 2019, at 19:17, brian crabtree notifications@github.com wrote:

 styling/formatting is easy to change as long as the core functionality we want is there (sidebar pages, ToC, search)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[oliviercreurer]

I was independently drafting some visual ideas for the fresh docs today, and was notified of this existing thread by @tehn -- hope I'm not stepping on any toes. I'm no web developer (I just have some basic css chops), but I do love design -- happy to help in any way I can.

Here's a basic side navigation layout I put together today (similar to work I did on the TT web manual), using crow as a lens to organize it:

https://monome-docs-nav.glitch.me/

And a couple of mobile-friendly versions too, where the nav shifts to the top of the content, and becomes sticky + collapsible:

[aidanreilly]

Olivier, these look really nice! Have you looked at the sample site i linked above? I think we could incorporate these ideas easily enough. I'm not a web developer either though, but i do enjoy hacking at these things.

@tehn @simonvanderveldt - need to decide if we are going to proceed with this just-the-docs theme. If we do, then we'll need to build a navigation for each and every markdown file. Not a difficult task, but probably time consuming. See here for detail: https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/

Basically, the current docs implementation uses hardcoded links at the top of every topic to provide the navigation. lofi, but it works. If we want a left hand nav, then we'll need to do a bit more to include the nav items. Different jekyll themes probably approach this in dfferent ways. This just-the-docs method is probably as advanced as any other jekyll theme that i've seen.

Open to suggestion/direction on how to proceed. I think we'll need to decide on a jekyll framework/theme, and then work to retrofit the content into that theme.

[simonvanderveldt]

I'm not sure I understand the question entirely, but I'll respond with another question :stuck_out_tongue:

Do we already know if we want the in page navigation to be in the sidebar or should it be at the top of the page itself?

[aidanreilly]

oh you mean we need some requirements? :)

[aidanreilly]

regarding my previous post, this is an example of the kind of header info we need per markdown file to provide a nav with this theme:

this is what is present in the doc files right now:

Not a complicated thing to fix, but time consuming.

[oliviercreurer]

I admit to being relatively ignorant of technical constraints (though of course I want to learn!), but I think a nice model would be for the side nav to change depending on the context so that it's more useful.

In essence, the /docs index would remain the same (perhaps just a light re-design would do), and then the side navigation would become available once you've jumped to a specific category from there (crow/norns/etc.) -- basically, the nav then functions as a ToC, since in that proposed model, all crow docs (for example) would be aggregated in a single page.

Curious to hear thoughts, pros/cons. I'll start mapping some examples out for easier discussion, and if it's easier to move design talk to a different issue here, I'm happy to open it.

[aidanreilly]

@oliviercreurer I opened this issue for the nav stuff: https://github.com/monome/docs/issues/164

[tehn]

it's confusing to have two issues about the same redesign so i'm going to say we merge this discussion with https://github.com/monome/docs/issues/164