search

lowRISC / opentitan

OpenTitan: Open source silicon root of trust
https://www.opentitan.org
Apache License 2.0
2.58k stars 777 forks source link

[docs] Broken links in `introduction.md` #17931

Closed jon-flatley closed 1 year ago

jon-flatley commented 1 year ago

Description

The links as they appear on docs.opentitan.org are currently broken for the Hardware and Software links. Looks like these are pointing at paths like https://opentitan.org/hw/index.html when they should point to https://opentitan.org/book/hw/index.html. In the markdown doc the link looks the same as it does for the [OpenTitan Earl Grey Chip Datasheet](https://opentitan.org/book/hw/top_earlgrey/doc/specification.html), which generates the correct link, so I'm not sure exactly what is going on here.

It looks like this may be fix by https://github.com/lowRISC/opentitan/pull/17924, but still filling this since these are high visibility links.

HU90m commented 1 year ago

Thanks for creating this issue. I should really have created it a little while ago, sorry.

This is a mdBook bug. I've created a bug report (https://github.com/rust-lang/mdBook/issues/2060) with a minimal reproduction and fix. TLDR; links work fine at https://opentitan.org/book/doc/introduction.html but the same page is used for https://opentitan.org/book/ with broken links.

To fix this without having to wait for upstream we could:

  1. move doc/introduction.md to README.md
  2. use a patched version of mdbook.
  3. use a redirect from /book/ to /book/doc/introduction.md in the site's deployment.

Some parts copied from https://github.com/lowRISC/opentitan/pull/17847#pullrequestreview-1378968940

jon-flatley commented 1 year ago

Thanks @HU90m! It is my opinion that fixing these links should be a priority, and if we're blocked on upstream we should implement one of your fixes to temporarily resolve the issue, and then revert the change once the bug in mdBook is fixed upstream. My instinct is to use the patched version of mdbook that you linked, since that will be easy to revert.

HU90m commented 1 year ago

That all sounds good, thanks for your input.

I'll get to work moving OT onto the patched version of mdbook first thing tomorrow.

msfschaffner commented 1 year ago

On this note, it looks like the individual links to the design specs (design names in the table) are also broken: https://opentitan.org/book/hw/index.html#top

HU90m commented 1 year ago

On this note, it looks like the individual links to the design specs (design names in the table) are also broken: https://opentitan.org/book/hw/index.html#top

Thanks for the heads up. This is captured in https://github.com/lowRISC/opentitan/issues/17591 and is next in priority after this issue.