jsdoc/jsdoc.github.io

Migrate to Docusaurus

qwertyvipul opened this issue · 4 comments

qwertyvipul commented

The current site misses out on a few important features now standard across modern documentation sites. Such as:

  1. Sidebar for quick navigation between pages and better context of the site heirarchy,
  2. Previous and next link to pages,
  3. Fixed TOC on top right for better context of current position in the page content hierarchy, and
  4. Search

This causes significant inconvenience to developers browsing the site, especially when in need for quick reference. Proposing to migrate from Metalsmith to Docusaurus as it provides the above features out of the box along with many others.

I tried this migration with my fork, and was able to do it with minimal changes in the existing markdown contents and without breaking the existing links and redirects. Refer:

  1. Resulting site
  2. Changelog

I will go ahead a raise a PR for the migration without Search feature. Read here for the Docusaurus search support.

oleksandr-dukhovnyy commented

Almost created the same PR.
Indeed, upgrading to a more modern look greatly optimizes the user experience.
I just spent over 10 minutes trying to verify that, for example, the @complexity parameter does not exist. To do this, I had to dig through the entire site.

If the effort is really small, then it's worth doing!

qwertyvipul commented

@Aleksandr-JS-Developer it's a one time effort. I have already created this non-breaking PR and the resulting site would be as good as the current one w.r.t existing experience, plus it will also have the additional features mentioned in the issue except search. However, I haven't been able to get any response from the maintainers, thus stuck with a pending PR.

  • 🚀1