Better navigation for documentation modules

[andy-hanson]

At https://crow-lang.org/doc, the left navigation bar has a line for every module in the standard library. This makes the page too tall.

I think the solution is to have a collapsed section for each directory (probably using details). I'm ambivalent about whethere there is recursive nesting where crow/io/net/ goes inside crow/io/, or if it's just its own section.

[bnn1]

@andy-hanson there's an easier solution, I think, but I'm not sure if it will fit you. Did you consider making left navigation scrollable?

[andy-hanson]

I think that would be better than the way it is now. I think the best solution would be to do both. A bigger improvement would be #3, but that's a lot more work.

[bnn1]

If you don't need to handle complex cases, simple search can be implemented without any library. It only needs an array of objects {label:string;href:string} and some filtering function like arr.filter((navSection) => navSection.includes(userInput)). It won't hurt to use something like fuse.js though.

I wanna try to take on these issues. Could you provide some details on the tasks? Basically I need to know what files to modify, i.e. which file contains navbar. I also need to research crow because I have no idea what's going on in crow files :D

[andy-hanson]

It's late so here's the quick explanation:

• The site is generated by make prepare-site which runs a crow script in site-src to generate site.

  • The .html files in site-src are fragments; they are mixed into a template from page-template.crow.
  • In the case of documentation there is document-template from document.crow which adds doc navigation before calling page-template. Documentation pages don't have any manually written HTML; it's all generated by document-content.crow which generates the HTML from the module definitions. (Generating search data would walk the same data as document-content but would output search terms instead of HTML.)
  • Since every documentation page has identical navigation, that's done in document-template. That takes all-paths str[] which is the list of all documentation pages, and builds a nav element out of that.
  • I did it this way, with the navigation in the document template, to keep things simple at first. If we want more complicated navigation, potentially all document.crow should do is create a JSON file with navigation information, and JS code would load that and be responsible for actually creating the DOM nodes for navigation. (There should still be a way for search engines to find the pages, though.)

• The site's JavaScript code is in site-src/script. These .js files are simply symlinked into site/script, meaning there's no real build system. The site has basically no JS code other than for the CrowRunnable element, which is used for the code examlpes, and is unrelated to this issue. So for this issue and #3 you'd pretty much be working from a blank slate on the JS side.

• Currently the only real resource for learning crow is the website. I also set up a gitter where you can post questions. Another way to learn is by reading the code in site-src/*.crow, which is a good example of a small crow program that does real work. I'll be more active during the weekend.

[bnn1]

So you want to programmatically manipulate DOM, i.e. add input element and search for specific doc page, group doc pages by sections, all using client-side js, is that right?

[andy-hanson]

I'm ambivalent whether the navigation is generated on the server or on the client -- if the changes to make aren't too great it may be simpler to continue doing it on the server. For the search box it's most convenient to do it on the client -- it makes deploying the site easier if there's no code running on the server, and the data to search shouldn't be too big, so I suspect search will be faster on the client anyway.

I think the different doc pages for each module should still be separate HTML documents with separate URLs, though.

[bnn1]

so I added input element to navbar and styled it a little. will do search logic now

[andy-hanson]

Looks good! If you need any help with the rest, I'll be monitoring https://gitter.im/crow-lang-org/community .