For this week in Topics in Open Source Development, I was tasked with performing a code reading of a specific feature in Docusaurus, and implementing said feature into my own project. The feature I selected was a search function. You can see it running live at https://paulkim26.github.io/til-to-html/.
What does this feature entail?
The feature I implemented was a search field, similar to the one found in Docusaurus. I added an HTML input field that, upon a change in input, will mark text in the generated static site that matches what was entered in the search field (source). It'll allow users to quick find text they are looking for and, in the future, across multiple pages - not just the current page. It works by:
- Reading the contents of a TIL post's HTML after it is generated.
- Checking for instances of the current keyword entered in the search field via a regex match (not including text encapsulated within the chevrons of HTML tags).
- Replacing matched text with a copy encapsulated between HTML
<mark>tags.
Why this feature?
Working with new features, frameworks, and tools, the experience of reading documentation is a critical part of it. I have been lucky to work with projects that feature really easy to read documentation such as USWDS and Bun, but I've also had the misfortune to work with pretty terrible documentation like JSDoc. The JSDoc documentation lacks a search field which makes searching for specific items an ordeal and also does not cover many hidden use cases. It provides less than the bare minimum for what it needs to do - a lot of the time I am forced to rely on external user documentation elsewhere to use JSDoc effectively. That was why I was drawn to the search field in particular in Docusaurus.
Comparison to the Docusaurus Search feature
The most important distinction is that it is an offline local search function and not the Algolia DocSearch powered search featured in Docusaurus. I considered implementing Algolia DocSearch in my application but realized that does not make sense in this context since Algolia DocSearch needs to scrape sites to generate its search results. til-to-html is a static site generator for short form posts in similar scope to a blog - it is not "documentation" in the sense that Algolia DocSearch is primarily built for. It would still be nice to be able to search for specific content within til-to-html, but without the extensive overhead and functionality that Algolia provides. I determined an offline solution would be more suited for this context.
Next Steps
This is just the start of the feature. At the moment, the search is limited to the current page - it is no better than the ctrl-f function of any browser. I plan to:
- Provide the ability to search between multiple pages
- Allow the user to see a list of all search result instances
- Allow users to quickly switch between generated pages via a table of contents either within a sidebar or an index page
If you're interested in helping out, take a look at the issues page - the more the merrier!
Issues: https://github.com/paulkim26/til-to-html/issues
Thanks for reading!
Top comments (0)