Convert specifications to mdbook
Per proposal 345, I want to convert our specifications to markdown and render them in mdbook.
The end result of the migration will be that:
- The torspec repository looks more like this.
- There is rendered torspec website looks more like this.
It looks like spec.tpo is available as a target for this rendering; @weasel (the current spec.tpo maintainer) has approved on IRC. There is a TPA ticket open for the admin side of the issue, and I've gotten some helpful advice there too.
On this ticket I'll be tracking the actual details of doing the migration. I won't do anything final without talking to more people, though.
Next steps here are:
-
Decide on the new layout we want for torspec.git. -
Decide on the URL layout we want for the new spec.tpo website. - Should we have a landing page, or should the mdbook content be the landing page?
- Should we leave a spot for RFCs?
-
Work on the migration scripts and their configuration (including where to break the sections), until they produces output we like, and it gives us the layout we want. -
Develop the CI process as needed to keep the site up to date. - Probably, publish to gitlab pages at first.
-
Figure out whose approval we need for this, and see what they think. -
Write documentation as needed to explain how to edit the spec. -
Decide how to maintain redirects and permalinks.
After we've done this stuff I think we are ready to start the migration.
Edited by Nick Mathewson