Migrate docs to docusaurus

[Keinberger]

Summary

This PR migrates the existing documentation from mdbook to Docusaurus. This includes syntax changes and structural updates.

---

🚨 DO NOT MERGE YET 🚨

Merging this PR before all other Docusaurus PRs are ready will break the docs deployment! Also, merging has to be done in correct order to ensure a smooth transition!

---

Note

1. This PR changes the markdown syntax from mdbook to Docusaurus. Please familiarize yourself with the new Docusaurus syntax.
2. The new markdown files have been moved to docs/src.

Changes

Syntax changes

As already mentioned before, this PR changes the markdown syntax of all docs markdown files.
Going forward all documentation will also be written using Docusaurus sytnax.

NOTE: Please review the updated Markdown files to understand the new format.

Local testing

To test docs locally before pushing changes:

1. Cd into docs:

cd docs

2. Install packages:

npm install

4. Start the local dev server:

npm run start:dev

Note: The index.md file might not appear in the correct sidebar order during local dev. In production deployments it will. To guarantee proper ordering, ensure index.md includes:

---
sidebar_position: 1
---

New Docs Architecture

The documentation system no longer relies on cron jobs or local scripts. Instead, changes are propagated through a CI-driven process. Here are the key changes:

1. Removal of cron task for initiating a bash script

Instead of relying on a cron task to update the docs, every repository now integrates a "trigger-docs-deploy.yml" workflow, which automatically triggers a rebuild and redeployment of the docs upon changes to next.

2. Versioning support

Upon Testnet deployments, a dedicated workflow inside of the miden-docs repository can be triggered to create a snapshot of the docs for that specific version. This workflow has to be triggered manually.

[Dominik1999]

To me it looks good. I left 3 small comments. I have built it locally and looked mostly on the layout.

[Dominik1999]

This :::note looks weird here and in other places. I think our initial intention was to give a definition for the datastructure, e.g., Vault, and the an explanation. But since there are only two sentences, let's try to get rid of the :::note here and in other places.

[Keinberger]

I agree, it looks weird now with how Docusaurus renders those :::note tags in comparison to the mdbook render.

[Keinberger]

I think it would be best to add that change as part of the "overhaul" that you mentioned down below, what do you think?

[PhilippGackstatter]

Looks good to me!

I mainly looked through the docs and they render very nicely 🎉.

Left a few comments, but mostly small things or questions. Feel free to address what you think makes sense.

[bobbinth]

Thank you! I've browsed through the new docs locally, and they look really good!

This is not a full review yet, but a few quesitons/comments:

• We probably should update the Makefile as there are some mdBook specific commands there (e.g., book, check-tools and install-tools).
• Related to the above, should we add a command to the Makefile to serve the docs? (i.e., similar to the current book command).
• We should probably also document somewhere that we need to install NPM for this to work. Maybe somewhere in the main README? We could also add NPM installation to the install-tools command, but not sure how difficult this would be.
• Do we want to have a CI job to make sure there are no build issues with the docs? Or would this be handled by the "deploy docs" workflow?
• What would we need to do to also deploy these docs locally? Similar to how we currently deploy the mdBook docs as a Github page at https://0xmiden.github.io/miden-base
  • I know one of the reasons we are moving to Docusaurus is to be able to show multiple doc versions. Would we also be able to do it locally? (i.e, would be awesome to have docs for main vs. next). Not something for this PR - but just curious if it'll work in the future.

[bobbinth]

Looks good! Thank you! Though, I primarily reviewed the high-level structure.

One thing: it would be great to add a brief comment in the trigger-deploy-docs.yml file explaining what it does. My understanding is that on every merge to next, it would trigger a rebuild of the docs in the miden-docs repo, which in turn would pull the latest docs from next branches of all relevant docs. But maybe I'm missing some detail.

[PhilippGackstatter]

Looks great! Thank you for the additional comments and explainers and migrating to YAML - much appreciated!

[bobbinth]

Question: why use a specific commit here?

[Keinberger]

This is related to a comment from Paul on the compiler docs PR: 0xMiden/compiler#692 (comment)

In essence we want to use specific SHA revision because of security considerations. The workflow's are using PATs, which have certain permissions and w do not necessarily want to just rely on tags, which could be overridden by a potentially unsafe ref.