Skip to content

Conversation

@Keinberger
Copy link
Collaborator

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.
  3. I separated the exported md files from non-exported md files that are intended as "internal docs". The exported files can be found inside of docs/src/external, internal docs inside of docs/src/internal.

Questions & Clarifications

I kept the md files inside of docs/src/internal to keep supporting mdbook, so that the internal docs can be hosted as an mdbook on 0xmiden.github.io/miden-node/. These files are files that are currently not exported to the Miden book.

That said, I believe it would be better to migrate these files to Docusaurus syntax as well. This would allow us to integrate the internal docs into the external documentation in the future, while also ensuring that developers only need to work with a single, consistent syntax (Docusaurus Markdown) instead of switching between mdBook and Docusaurus.

@bitwalker What do you think?

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/external
  1. Install packages:
npm install
  1. 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.

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

This reverts commit 99737c4, reversing
changes made to c2ab35b.
@Keinberger Keinberger requested a review from bitwalker October 3, 2025 10:22
@Keinberger Keinberger merged commit 810d1a1 into next Oct 23, 2025
12 checks passed
@Keinberger Keinberger deleted the chore/docusaurus-migration-new branch October 23, 2025 09:26
@github-actions github-actions bot mentioned this pull request Nov 5, 2025
This was referenced Nov 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants