Skip to content

Remove docs.sourcegraph.com sidebar, simplify template

Warren Gifford requested to merge docsite-template into main

Created by: sqs

Removes the sidebar on https://docs.sourcegraph.com because it is:

  • Clunky: It doesn't work in the really smooth way that Stripe's API docs sidebar works. The top-level topics aren't fixed, hierarchy is displayed visually in 2 different ways, clicking to a different top-level section does not preserve your context, mobile UI is not intuitive IMO, etc.
  • Not regularly maintained: Many times, people forget to add pages to the sidebar, because they're just editing the Markdown files and don't realize they need to do that. There is no static check that a page is linked in it (nor would we want every page to be likned in it), and it's a judgment call as to whether a page gets added. This means it's not a reliable or well thought-through way to navigate.
  • Very long
  • Inconsistent: In the screenshot below (for example), there are 2 different casings for the badges new/Beta, and both sentence case and title case are used.

Here is a screenshot of the sidebar that this PR removes:

image

@kghopson is evaluating our doc site and will likely choose to use a different tool for generating it. In the meantime, I would like to remove this debt and just rely on the Markdown pages' content to navigate, as we do in the Sourcegraph handbook. For example, the site admin page's content should link to all of the relevant pages in the site admin section.

In making this change, I noticed that there was a lot of unused CSS/HTML, so I also cleaned that up. There are still lots of TODOs in this branch that I'll fix before merging (such as the version selector).

If you disagree with this change: Yeah, I mean, I would like to have a nice doc sidebar as well. But I'd rather not invest more time in this old doc sidebar that has many known problems, when @kghopson is likely to pick a new doc generator tool that will handle this much better. We know that in-content navigation works acceptably for the handbook (and it's all GitLab had on https://docs.gitlab.com until a few months ago). If you still disagree and think we should invest time in this, please say so. 😄

(Discussion started in https://sourcegraph.slack.com/archives/C07KZF47K/p1598388973084000?thread_ts=1598295302.057500&cid=C07KZF47K.)

Merge request reports