I’m excited to share a new feature I’ve been working on for swift-docc-render - Quick navigation. The goal is to create an accessible, easy and fast way to navigate and discover symbols in the documentation through fuzzy search. Quick navigation aims to bring a similar experience to what you achieve using Open Quickly in Xcode and other search tools inside IDEs or web-based documentation.
For me, this is particularly exciting because improves the search experience within the web-rendered documentation, making it easier for the community to find what they need, and allowing the reader to discover and quickly jump through symbols without having to remember the exact name. Including this type of feature on swift-docc-render makes the whole documentation experience more robust and enjoyable.
- Fuzzy search - Quick navigation allows approximate match between the user input and the symbol names, returning results relevant to the user.
- Symbols ranking - Results are sorted in a way that the most relevant ones are at the top of the list. This is done using similarity metrics, such as the length difference between the input and the match, the length of the symbol name, and how far from the beginning of the string the match occurs.
- Keyboard navigation - This feature will be fully accessible via keyboard shortcuts, making it easy to perform queries even when the navigation bar is collapsed.
The UI consists of a modal containing a text input and a list, the list is displayed once the user starts typing, and the query matches get ordered by similarity. This modal can be opened by clicking the
/ button inside the navbar input filter and closed by clicking outside the container or the
Interactions with the modal can be done via keyboard shortcuts:
⌘+shift+oto open the modal
ESCkey to dismiss the modal
- Up and down arrow keys to move through the list of results
Enterkey to access the selected symbol
I've set up a prototype on my argument-parser fork with the proposed feature, you can test it here https://sofiaromorales.github.io/swift-argument-parser/documentation/argumentparser/
Quick navigation is still under development, but I'd love to hear your feedback and suggestions!
One of the biggest questions we have right now is where to place the button to open the modal (currently located inside the sidebar filter input) so that it makes the most sense with the expected functionality creating a great user experience.
The things that are on the roadmap for the upcoming weeks are:
- Improve a11y
- Improve the sorting algorithm by prioritizing results that match the input by being case sensitive
- Fix performance bugs in larger documentations
Quick navigation is currently part of this PR https://github.com/apple/swift-docc-render/pull/396 under the
quickNavigation feature flag. I'm still in the process of polishing and fixing bugs, so I'd highly appreciate that if you find any bugs while testing the feature to file an issue here.
Some of the things that would be nice to work on in the future regarding Quick navigation are:
- Add Quick navigation in
/tutorials. Right now the modal can only be opened on the
- Add the symbol abstract into the information displayed for each list item, this would provide the reader more context about the symbol without having to access it. We would have to add the abstract to the
index.jsonfile generated by the compiler, significantly increasing the file size which could cause performance issues.
- Match the sidebar filtering algorithm to the Quick navigation filtering algorithm. Currently, the sidebar only does exact matches between the user input and the symbol name, and it might be beneficial to do partial matches here as well.
I look forward to hearing your feedback!