feat: add initial book setup (#869)

* feat: add initial book setup

* chore: update branch for real CI

* feat: add Justfile and spellcheck

.github/workflows/publish-mdbook.yml

@@ -0,0 +1,51 @@
+name: Publish mdBook to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "book/**"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Setup mdbook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "latest"
+
+      - name: Install mdbook plugins
+        run: |
+          cargo install mdbook-katex mdbook-linkcheck mdbook-mermaid just
+
+      - name: Install pnpm
+        run: npm install -g [email protected]
+
+      - name: Install pnpm deps
+        run: pnpm i --frozen-lockfile
+
+      - name: Build the book
+        run: |
+          cd book
+          just lint-book-toc
+          mdbook build
+
+      - name: Add CNAME file
+        run: echo "vm.axiom.xyz" > ./book/CNAME
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: book

book/.gitignore

@@ -0,0 +1 @@
+node_modules/**

book/.markdownlint.json

@@ -0,0 +1,18 @@
+{
+    "line_length": {
+      "line_length": 120,
+      "strict": false,
+      "stern": false,
+      "code_blocks": false,
+      "tables": false
+    },
+    "no-duplicate-heading": {
+      "siblings_only": true
+    },
+    "no-blanks-blockquote": false,
+    "no-empty-links": false,
+    "single-title": false,
+    "no-emphasis-as-heading": false,
+    "no-duplicate-header": false,
+    "no-inline-html": false
+}

book/Justfile

@@ -0,0 +1,58 @@
+
+set positional-arguments
+
+# default recipe to display help information
+default:
+  @just --list
+
+# Install required dependencies
+deps:
+    cargo install mdbook mdbook-katex mdbook-linkcheck mdbook-mermaid
+    pnpm i --frozen-lockfile
+
+# Lint the workspace for all available targets
+lint: lint-book-md-check lint-book-toc-check lint-filenames lint-book-spelling
+
+# Updates all files to fix linting issues
+lint-fix: lint-book-md-fix lint-book-toc
+
+# Validates markdown file formatting
+lint-book-md-check:
+    npx markdownlint-cli2 "./src/**/*.md"
+
+# Updates markdown files formatting to satisfy lints
+lint-book-md-fix:
+    npx markdownlint-cli2 --fix "./src/**/*.md"
+
+# Validates Table of Content Sections with doctoc
+lint-book-toc-check:
+    npx doctoc '--title=**Table of Contents**' ./src && git diff --exit-code ./src
+
+# Updates Table of Content Sections with doctoc
+lint-book-toc:
+    npx doctoc '--title=**Table of Contents**' ./src
+
+# Validates spelling using cspell
+lint-book-spelling:
+    npx cspell "./**/*.md"
+
+# Updates cspell words file with new words
+lint-book-spelling-fix:
+    npx cspell --words-only --unique "./**/*.md" | sort --ignore-case | uniq > words.txt
+
+lint-filenames:
+    #!/usr/bin/env bash
+    for file in $(find ./specs -type f); do
+      if [[ "$file" == *_* ]]; then
+        echo "File with underscore found: $file"
+        exit 1
+      fi
+    done
+    echo "Filename linting complete"
+
+build:
+    mdbook build
+
+# Serves the mdbook locally
+serve *args='':
+    mdbook serve $@

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Yi Sun"]
+language = "en"
+multilingual = false
+src = "src"
+title = "axVM Book"

book/cspell.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/packages/cspell-types/cspell.schema.json",
+    "version": "0.2",
+    "dictionaryDefinitions": [
+      {
+        "name": "words",
+        "path": "./words.txt",
+        "addWords": true
+      }
+    ],
+    "dictionaries": [
+      "words"
+    ],
+    "ignorePaths": [
+      "node_modules",
+      "./words.txt"
+    ],
+    "overrides": [
+      {
+        "filename": "**/*.md",
+        "ignoreRegExpList": []
+      }
+    ]
+}

book/package.json

@@ -0,0 +1,14 @@
+{
+    "name": "specs",
+    "version": "1.0.0",
+    "private": true,
+    "engines": {
+      "node": ">=16",
+      "pnpm": ">=9"
+    },
+    "dependencies": {
+      "doctoc": "^2.2.1",
+      "markdownlint-cli2": "0.4.0",
+      "cspell": "^8.1.3"
+    }
+}