Migrate docs from mdbook 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!

---

BEFORE MERGING: Update this PR to correctly implement testing on the FPI tutorial.

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.
3. Hidden # comments in Rust code blocks (previously supported by mdBook) have been removed.
4. Despite the removal of # comments, code blocks are still compatible with the cargo test --doc workflow. Typically, only the final tutorial code snippet will be compiled and executed.

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

3. 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.

[Keinberger]

Hey @partylikeits1983 @mmagician ,

Based on discussions I had with Philipp Gackstatter and Bobbin on the Docusaurus PR on the miden-base repository, I also included some more changes on this branch:

• _category_.json files are now in YAML format. That way we can add a comment in each file to explain the position parameter
• Added a small section in the README that explains the docs architecture (NPM dependencies and absorption into main docs page)
• Added a new build-docs workflow to check md syntax for the exported docs
• trigger-deploy.yml workflow
  • Added a specific SHA ref for safety (since it uses a personal access token)
  • Amended the workflow to only trigger on changes to the docs directory

Let me know your thoughts and if the PR is good to go!

[partylikeits1983]

Amazing work! LGTM

I took a relatively brief look at the PR. I ran the docs locally, everything seems to look good.

Mainly was going off of this link: https://animated-adventure-wrvg9jk.pages.github.io/

The only thing there I think is to add the Miden logo at the top left corner.

Only thing left to do is resolve merge conflicts and add latest changes in mdbook docs to this docusaurus PR

[Keinberger]

The only thing there I think is to add the Miden logo at the top left corner.

Yes, you're absolutely right! Before the docs are migrated, we will have a complete custom design for them. Currently working with Ahmad on that. I'm sure we will add that too!

Only thing left to do is resolve merge conflicts and add latest changes in mdbook docs to this docusaurus PR

Sounds good, I'm on it!