Feat: Upgrade to vocs static site generator (#256)

* feat: migrate frontend framework from mdbook to vocs  (#185)

* feat: migration to vocs

* Update CONTRIBUTING.md

* Update README.md

* fix: pr review requested changes

* temp: remove pages

* chore: Anchors in listings

* feat: voc sidebar config

* feat: migrate listings and book to vocs

* chore: npm -> pnpm

* ci/cd: fix build

* feat: footer

* feat: add tailwindcss

* feat: styling and configuration

* feat: mathjax support

* feat: collapsible sidebar css

* ci/cd: remove mdbook workflow

* feat: cairo syntax hl

* style: minor improvements

* fix: mdbook leftover anchors

* feat: collapsible sidebar

* feat: themes, inline highlighting, minor fixes

* ci/cd: add .npmrc file

---------

Co-authored-by: Kushagra Sarathe <76868364+kushagrasarathe@users.noreply.github.com>

.gitignore

@@ -1,6 +1,6 @@
-book
-target
-output
+node_modules
+.env
+dist/*
 
 # Editors tmp files.
 *~
@@ -11,4 +11,10 @@ output
 .vscode/settings.json
 **/starkli-wallet
 
-node_modules
+# From previous mdbook build
+book/*
+target/*
+src/**/*.md
+
+node_modules
+

.npmrc

@@ -0,0 +1 @@
+node-linker=hoisted

CONTRIBUTING.md

@@ -11,14 +11,12 @@ Please note we have a code of conduct, please follow it in all your interactions
 - [Contributing](#contributing)
   - [Table of Contents](#table-of-contents)
   - [Setup](#setup)
-  - [MdBook](#mdbook)
+  - [Working with Markdown Files](#working-with-markdown-files)
   - [Adding a new chapter](#adding-a-new-chapter)
   - [Adding a new Cairo program](#adding-a-new-cairo-program)
     - [Verification script](#verification-script)
     - [Tests](#tests)
-    - [Use of anchor](#use-of-anchor)
-  - [Translations](#translations)
-    - [Initiate a new translation for your language](#initiate-a-new-translation-for-your-language)
+    - [Use of region](#use-of-region)
   - [Code of Conduct](#code-of-conduct)
     - [Our Pledge](#our-pledge)
     - [Our Standards](#our-standards)
@@ -31,33 +29,41 @@ Please note we have a code of conduct, please follow it in all your interactions
 
 1. Clone this repository.
 
-2. Rust related packages:
+2. Install the required dependencies using pnpm:
 
-   - Install toolchain providing `cargo` using [rustup](https://rustup.rs/).
-   - Install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and the required extension with `cargo install mdbook  mdbook-i18n-helpers mdbook-last-changed `.
+```
+pnpm i
+```
 
 3. Install `scarb` using [asdf](https://asdf-vm.com/) with `asdf install`. Alternatively, you can install `scarb` manually by following the instructions [here](https://docs.swmansion.com/scarb/).
 
-## MdBook
+4. Start the development server:
 
-All the Markdown files **MUST** be edited in english. To work locally in english:
+```
+pnpm dev
+```
 
-- Start a local server with `mdbook serve` and visit [localhost:3000](http://localhost:3000) to view the book.
-  You can use the `--open` flag to open the browser automatically: `mdbook serve --open`.
+## Working with Markdown Files
 
-- Make changes to the book and refresh the browser to see the changes.
+All Markdown files (\*.md) MUST be edited in English. Follow these steps to work locally with Markdown files:
 
-- Open a PR with your changes.
+- Make changes to the desired .md files in your preferred text editor.
+- Save the changes, and your browser window should automatically refresh to reflect the updates.
+- Once you've finished making your changes, build the application to ensure everything works as expected:
+  ```
+  pnpm build
+  ```
+- If everything looks good, commit your changes and open a pull request with your modifications.
 
 ## Adding a new chapter
 
-To add a new chapter, create a new markdown file in the `src` directory. All the Markdown files **MUST** be edited in english. In order to add them to the book, you need to add a link to it in the `src/SUMMARY.md` file.
+- To add a new chapter, create a new markdown file in the `pages` directory. All the Markdown files **MUST** be edited in english. In order to add them to the book, you need to add in the `vocs.config.ts` file.
 
-Do not write directly Cairo program inside the markdown files. Instead, use code blocks that import the Cairo programs from the `listing` directory. These programs are bundled into scarb projects, which makes it easier to test and build all programs. See the next section for more details.
+- Do not write directly Cairo program inside the markdown files. Instead, use code blocks that import the Cairo programs from the `listings` directory. These programs are bundled into scarb projects, which makes it easier to test and build all programs. See the next section for more details.
 
 Be sure to check for typos with `typos`:
 
-```shell
+```bash [Terminal]
 cargo install typos-cli
 typos src/
 ```
@@ -159,7 +165,8 @@ Every listing needs to have atleast integration tests:
 
 Add your contract in a specific file, you can name it `contract.cairo` or anything else. You can also add other files if needed.
 
-You should add the tests in the same file as the contract, using the `#[cfg(test)]` flag and a `tests` module. With the usage of ANCHOR, the tests will not be displayed in the book but can be optionally be displayed by using the `{{#rustdoc_include ...}}` syntax.
+You should add the tests in the same file as the contract, using the `#[cfg(test)]` flag and a `tests` module.
+<!-- With the usage of ANCHOR, the tests will not be displayed in the book but can be optionally be displayed by using the `{{#rustdoc_include ...}}` syntax. -->
 
 Here's a sample `lib.cairo` file:
 
@@ -171,9 +178,9 @@ mod contract;
 And in the `contract.cairo` file:
 
 ```cairo
-// ANCHOR: contract
+// [!region contract]
 // Write your contract here
-// ANCHOR_END: contract
+// [!endregion contract]
 
 #[cfg(test)]
 mod tests {
@@ -183,27 +190,26 @@ mod tests {
 
 You can use Starknet Foundry to write and run your tests.
 
-### Use of anchor
+### Use of region
 
 You can add delimiting comments to select part of the code in the book.
 
 ```cairo
 file.cairo:
 
 a
-// ANCHOR: anchor_name
+// [!region region_name]
 b
-// ANCHOR_END: anchor_name
+// [!endregion region_name]
 c
 ```
 
 Then, in the markdown file, you can use the following syntax to include only the code between the delimiting comments:
 
 ````markdown
-````cairo
-{{#include ../../listings/path/to/listing/src/contract.cairo:anchor_name}}
-\```
-````
+    ```cairo
+    // [!include ~/listings/src/contract.cairo:region_name]
+    ```
 ````
 
 This will result in the following code being included in the book:
@@ -212,39 +218,21 @@ This will result in the following code being included in the book:
 b
 ```
 
-Using `#rustdoc_include` you can have the same result, but users can expand the code in the book to see the whole file (used for showing tests):
+To render code in tabs format you can use `:::code-group`. Example you can render contract and tests in separate tabs like this:
 
-````markdown
-````cairo
-{{#rustdoc_include ../../listings/path/to/listing/src/contract.cairo:anchor_name}}
-\```
 ````
-````
-
-## Translations
+    :::code-group
 
-> Translations efforts are currently on hold. If you are interested in helping out, please send a message in the telegram channel.
+    ```cairo [contract]
+    // [!include ~/listings/src/contract.cairo:contract]
+    ```
 
-To work with translations, those are the steps to update the translated content:
+    ```cairo [tests]
+    // [!include ~/listings/src/contract.cairo:tests]
+    ```
 
-- Run a local server for the language you want to edit: `./translations.sh zh-cn` for instance. If no language is provided, the script will only extract translations from english.
-
-- Open the translation file you are interested in `po/zh-cn.po` for instance. You can also use editors like [poedit](https://poedit.net/) to help you on this task.
-
-- When you are done, you should only have changes into the `po/xx.po` file. Commit them and open a PR.
-  The PR must stars with `i18n` to let the maintainers know that the PR is only changing translation.
-
-The translation work is inspired from [Comprehensive Rust repository](https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md).
-
-You can test to build the book with all translations using the `build.sh` script and serve locally the `book` directory.
-
-### Initiate a new translation for your language
-
-If you wish to initiate a new translation for your language without running a local server, consider the following tips:
-
-- Execute the command `./translations.sh new xx` (replace `xx` with your language code). This method can generate the `xx.po` file of your language for you.
-- To update your `xx.po` file, execute the command `./translations.sh xx` (replace `xx` with your language code), as mentioned in the previous chapter.
-- If the `xx.po` file already exists (which means you are not initiating a new translation), you should not run this command.
+    :::
+````
 
 ## Code of Conduct
 

README.md

@@ -10,18 +10,15 @@ Please refer to the Contribution Guidelines page:
 - [Contributing](CONTRIBUTING.md#contributing)
   - [Table of Contents](CONTRIBUTING.md#table-of-contents)
   - [Setup](CONTRIBUTING.md#setup)
-  - [MdBook](CONTRIBUTING.md#mdbook)
+  - [Working with Markdown Files](CONTRIBUTING.md#working-with-markdown-files)
   - [Adding a new chapter](CONTRIBUTING.md#adding-a-new-chapter)
   - [Adding a new Cairo program](CONTRIBUTING.md#adding-a-new-cairo-program)
-    - [Verification script](CONTRIBUTING.md#verification-script)
     - [Tests](CONTRIBUTING.md#tests)
-    - [Use of anchor](CONTRIBUTING.md#use-of-anchor)
-  - [Translations](CONTRIBUTING.md#translations)
-    - [Initiate a new translation for your language](CONTRIBUTING.md#initiate-a-new-translation-for-your-language)
+    - [Use of region](CONTRIBUTING.md#use-of-region)
   - [Code of Conduct](CONTRIBUTING.md#code-of-conduct)
     - [Our Pledge](CONTRIBUTING.md#our-pledge)
     - [Our Standards](CONTRIBUTING.md#our-standards)
     - [Our Responsibilities](CONTRIBUTING.md#our-responsibilities)
     - [Scope](CONTRIBUTING.md#scope)
     - [Enforcement](CONTRIBUTING.md#enforcement)
-    - [Attribution](CONTRIBUTING.md#attribution)
+    - [Attribution](CONTRIBUTING.md#attribution)

Scarb.toml

@@ -3,7 +3,7 @@ members = [
   "listings/getting-started/*",
   "listings/applications/*",
   "listings/advanced-concepts/*",
-  "listings/templates/*",
+  "listings/cairo_cheatsheet",
 ]
 
 [workspace.scripts]