system76 / firmware-open

System76 Open Firmware
Other
951 stars 86 forks source link

Build docs with mdBook #383

Closed crawfxrd closed 6 months ago

crawfxrd commented 1 year ago

Allow generating HTML output of docs for easy navigation and reading.

leviport commented 6 months ago

screenshot-2024-02-21-21-28-07

The current home page when building & running with mdbook serve and visiting localhost:3000 is this index file, which seems a bit odd. Also, when running the command displayed above, I'm still taken to this Index page, which displays the command I just ran, which could lead to some confusion. Would we want to populate the Index page with something like a ToC, or a generalized summary about Open Firmware instead, kind of like tech-docs?

crawfxrd commented 6 months ago

TOC is generated by SUMMARY.md, which should be expanded by default (otherwise toggled from the button on the menu bar).

It is just filler for now. The first interaction will likely be to open index.md either by clicking the link in README.md on GitHub or opening the file in an editor from a local checkout. It could be moved to a section to be more explicit about generating and viewing the docs.