Quick navigation in DocC Render

Development Swift-DocC
,
7

Hi everyone! I made an overview and some designs of how the Quick Navigation in DocC Render could work.

The idea here is to design and implement a feature that allows the user to easily navigate the documentation symbols and file through searching and filter capabilities. Similar to what most IDEs and some web apps have, a modal with a search bar presented to the user at the center of the screen, for example, Xcode has Open Quickly that you can enable by pressing ⌘ + shift + o.

Quick Navigation modal in SlothCreator DocC documentation
Quick Navigation modal in SlothCreator DocC documentation2916×1776 311 KB

1. Search

So the main function of this Quick Navigation feature would be to list the symbol names that match the user input, this can be accomplished using fuzzy search.

Searching symbol name in SlothCreator DocC Quick Navigation
Searching symbol name in SlothCreator DocC Quick Navigation2916×1776 313 KB

2. Filter by type

Another function that I found in some IDE and thought might be useful (but not sure if it fits inside the project scope) is to add a Filter by symbol type functionality, similar to the normal search, this will show the symbols that it type matches the user input, this functionality would be activated when the user types the : character at the beginning of the input.

Searching symbol type in SlothCreator DocC Quick Navigation
Searching symbol type in SlothCreator DocC Quick Navigation2916×1776 295 KB

3. Keyboard navigation

To make the Quick Navigation feature accessible and easy to navigate I came up with different keyboard shortcuts to move around

  • To open the Quick Navigation search bar ⌘ + shift + o just like in Xcode
  • To navigate the result list up and down arrow keys
  • To access the file ↵

Questions for the community

  1. There's any standard for organizing the results in this type of searching element? I could notice from different IDEs there's a pattern where the exact match goes on top of the list and the partial ones go at the end, but I was wondering if there's any documentation from W3 or any other organization regarding this. Also for ordering the result elements when they have the same match relevance, it should be alphabetically ordered? ordered by symbol type?

  2. In the design I added the symbol path next to the name, tried to follow the same structure as the sidebar, but idk if it makes sense to put it there since there could be multiple paths for a single symbol (SlothGenerator for example). Maybe following the page routing and using that for the symbols paths could work for this?

  3. Regarding the Filter by Type functionality, do you think there's a benefit and is a good addition to the feature? like, do you see yourself needing to filter by type? And if the answer is yes, there should be any type of partial string matching between the user input and the results? I kinda see it more like a total match

@marinaaisa @beatriz I was wondering if there's any problem if I contact you privately to get some feedback on my proposal before submitting it, also if anyone else would like to take a look lmk, It would be huge help.

Any other ideas or feedback would be appreciated! Have a great day :smile:

5 Likes