docs: convert core and prover docs to mdbook project and add CI (#3275)

## What ❔

* [x] Convert `docs` core project documentation to [mdBook
project](https://rust-lang.github.io/mdBook/)
* [x] Convert `prover/docs` prover project documentation to [mdBook
project](https://rust-lang.github.io/mdBook/)
* [x] Add CI workflows to build, test, and deploy versioned
documentation for these projects using
https://github.com/matter-labs/deploy-mdbooks action

<!-- What are the changes this PR brings about? -->
<!-- Example: This PR adds a PR template to the repo. -->
<!-- (For bigger PRs adding more context is appreciated) -->

## Why ❔

Fixes #3185

To improve documentation visibility and usability in ZKsync era
repository.

<!-- Why are these changes done? What goal do they contribute to? What
are the principles behind them? -->
<!-- Example: PR templates ensure PR reviewers, observers, and future
iterators are in context about the evolution of repos. -->

## Tests

Deployed documentation examples are available in the fork:
* For core project:
https://antonbaliasnikov.github.io/zksync-era/core/latest/
* For prover project:
https://antonbaliasnikov.github.io/zksync-era/prover/latest/

## Design decisions

It was chosen to use two different workflow files for documentation
deployments to keep CI reliable and easy to support regardless of a bit
of boilerplate code. [Solution with the unified
workflow](https://github.com/antonbaliasnikov/zksync-era/blob/main/.github/deploy-docs.yml)
for both projects was implemented but rejected as it is overcomplicated
and more difficult to support in the long term.

## Checklist

<!-- Check your PR fulfills the following items. -->
<!-- For draft PRs check the boxes as you complete them. -->

- [x] PR title corresponds to the body of PR (we generate changelog
entries from PRs).
- [x] Tests for the changes have been added / updated.
- [x] Documentation comments have been added / updated.
- [x] Code has been formatted via `zkstack dev fmt` and `zkstack dev
lint`.

.github/workflows/deploy-core-docs.yml

@@ -0,0 +1,67 @@
+name: Deploy core docs
+
+on:
+  push:
+    branches:
+      - "main"
+    tags:
+      - "core-v*.*.*"
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-core-docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-core-docs.yml'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch, tag or commit to deploy the core docs. If empty, use the ref that triggered the workflow."
+        required: false
+        default: ""
+      version:
+        type: string
+        description: "Version of the documentation to deploy"
+        required: false
+        default: "latest"
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+
+  deploy-core-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      DOCS_DIR: 'docs'
+      PROJECT: 'core'
+      ENABLE_TESTS: false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        with:
+          ref: ${{ inputs.ref || '' }}
+
+      - name: Extract version from tag
+        if: startsWith(github.ref, 'refs/tags/')
+        id: extract-version
+        shell: 'bash -ex {0}'
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION="${TAG#*-}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Deploy core docs
+        uses: matter-labs/deploy-mdbooks@77856145362bf23834f2e54a44a928790c4bee7c # v1
+        with:
+          version: ${{ inputs.version || steps.extract-version.outputs.version || github.ref_name }}
+          docs-dir: ${{ env.DOCS_DIR }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          enable-tests: ${{ env.ENABLE_TESTS }}
+          project: ${{ env.PROJECT }}
+          deploy: ${{ github.event_name != 'pull_request' }}

.github/workflows/deploy-prover-docs.yml

@@ -0,0 +1,67 @@
+name: Deploy prover docs
+
+on:
+  push:
+    branches:
+      - "main"
+    tags:
+      - "prover-v*.*.*"
+    paths:
+      - 'prover/docs/**'
+      - '.github/workflows/deploy-prover-docs.yml'
+  pull_request:
+    paths:
+      - 'prover/docs/**'
+      - '.github/workflows/deploy-prover-docs.yml'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch, tag or commit to deploy the prover docs. If empty, use the ref that triggered the workflow."
+        required: false
+        default: ""
+      version:
+        type: string
+        description: "Version of the documentation to deploy"
+        required: false
+        default: "latest"
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+
+  deploy-prover-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      DOCS_DIR: 'prover/docs'
+      PROJECT: 'prover'
+      ENABLE_TESTS: false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        with:
+          ref: ${{ inputs.ref || '' }}
+
+      - name: Extract version from tag
+        if: startsWith(github.ref, 'refs/tags/')
+        id: extract-version
+        shell: 'bash -ex {0}'
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION="${TAG#*-}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Deploy prover docs
+        uses: matter-labs/deploy-mdbooks@77856145362bf23834f2e54a44a928790c4bee7c # v1
+        with:
+          version: ${{ inputs.version || steps.extract-version.outputs.version || github.ref_name }}
+          docs-dir: ${{ env.DOCS_DIR }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          enable-tests: ${{ env.ENABLE_TESTS }}
+          project: ${{ env.PROJECT }}
+          deploy: ${{ github.event_name != 'pull_request' }}

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,32 @@
+[book]
+authors = ["ZKsync team"]
+language = "en"
+multilingual = false
+src = "src"
+title = "ZKsync Era Documentation"
+
+[output.html]
+smart-punctuation = true
+mathjax-support = true
+git-repository-url = "https://github.com/matter-labs/zksync-era/tree/main/docs"
+edit-url-template = "https://github.com/matter-labs/zksync-era/tree/main/docs/{path}"
+additional-js = ["js/version-box.js", "js/mermaid-init.js"]
+additional-css = ["css/version-box.css"]
+
+[output.html.playground]
+editable = true
+line-numbers = true
+
+[output.html.search]
+limit-results = 20
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 2
+boost-paragraph = 1
+expand = true
+heading-split-level = 2
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"

docs/css/version-box.css

@@ -0,0 +1,46 @@
+#version-box {
+    display: flex;
+    align-items: center;
+    margin-right: 15px; /* Space from the right side */
+    background-color: transparent; /* Make the box background transparent */
+}
+
+/* Base styles for the version selector */
+#version-selector {
+    background-color: transparent; /* Remove background color */
+    border: 1px solid #4a5568;     /* Subtle border */
+    border-radius: 4px;            /* Rounded edges */
+    padding: 5px 10px;             /* Padding inside dropdown */
+    font-size: 0.9em;
+    font-weight: normal;
+    outline: none;                 /* Removes default focus outline */
+    cursor: pointer;
+}
+
+/* Text color for dark themes */
+.theme-navy #version-selector,
+.theme-coal #version-selector {
+    color: #f7fafc; /* Light text color for dark backgrounds */
+}
+
+/* Text color for light theme */
+.theme-light #version-selector {
+    color: #333333; /* Dark text color for light background */
+}
+
+/* Hover effect for better user feedback */
+#version-selector:hover {
+    background-color: rgba(255, 255, 255, 0.1); /* Light hover effect */
+}
+
+/* Optional: Style for when the selector is focused */
+#version-selector:focus {
+    border-color: #63b3ed; /* Accent color for focused state */
+}
+
+.right-buttons {
+    display: flex;
+    flex-direction: row;     /* Aligns items in a row, left to right */
+    align-items: center;     /* Centers items vertically */
+    gap: 10px;               /* Adds space between items */
+}

docs/js/mermaid-init.js

@@ -0,0 +1,35 @@
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();

docs/js/version-box.js

@@ -0,0 +1,61 @@
+document.addEventListener('DOMContentLoaded', function () {
+    // Get the base URL from the mdBook configuration
+    const baseUrl = document.location.origin + '/zksync-era/core';
+
+    // Function to create version selector
+    function createVersionSelector(versions) {
+        const versionSelector = document.createElement('select');
+        versionSelector.id = 'version-selector';
+
+        // Get the current path
+        const currentPath = window.location.pathname;
+
+        // Iterate over the versions object
+        for (const [versionName, versionUrl] of Object.entries(versions)) {
+            const option = document.createElement('option');
+            option.value = versionUrl + '/';
+            option.textContent = versionName;
+
+            // Check if the current URL matches this option's value
+            if (currentPath.includes(option.value)) {
+                option.selected = true; // Set this option as selected
+            }
+
+            versionSelector.appendChild(option);
+        }
+
+        // Event listener to handle version change
+        versionSelector.addEventListener('change', function () {
+            const selectedVersion = versionSelector.value;
+            // Redirect to the selected version URL
+            window.location.href = '/zksync-era/core' + selectedVersion;
+        });
+
+        return versionSelector;
+    }
+
+    // Fetch versions from JSON file
+    fetch(baseUrl + '/versions.json')
+        .then((response) => {
+            if (!response.ok) {
+                throw new Error('Network response was not ok ' + response.statusText);
+            }
+            return response.json();
+        })
+        .then((data) => {
+            const versionSelector = createVersionSelector(data);
+            const nav = document.querySelector('.right-buttons');
+
+            if (nav) {
+                const versionBox = document.createElement('div');
+                versionBox.id = 'version-box';
+                versionBox.appendChild(versionSelector);
+                nav.appendChild(versionBox); // Append to the .right-buttons container
+            } else {
+                console.error('.right-buttons element not found.');
+            }
+        })
+        .catch((error) => {
+            console.error('There has been a problem with your fetch operation:', error);
+        });
+});

docs/src/README.md

@@ -0,0 +1,26 @@
+# Introduction
+
+Welcome to the documentation! This guide provides comprehensive insights into the architecture, setup, usage, and
+advanced features of ZKsync.
+
+## Documentation Structure
+
+- **Guides**: The Guides section is designed to help users at every level, from setup and development to advanced
+  configuration and debugging techniques. It covers essential topics, including Docker setup, repository management, and
+  architecture.
+
+- **Specs**: This section dives into the technical specifications of our system. Here, you’ll find detailed
+  documentation on data availability, L1 and L2 communication, smart contract interactions, Zero-Knowledge proofs, and
+  more. Each topic includes an in-depth explanation to support advanced users and developers.
+
+- **Announcements**: This section highlights important updates, announcements, and committee details, providing
+  essential information to keep users informed on the latest changes.
+
+## Getting Started
+
+Feel free to explore each section according to your needs. This documentation is designed to be modular, so you can jump
+to specific topics or follow through step-by-step.
+
+---
+
+Thank you for using our documentation!