docs: rework documentation (#238)

* Rework documentation

* Address code review feedback

* Add note about installing builtins

* Apply suggestions from code review

Co-authored-by: Till Schneidereit <till@tillschneidereit.net>

* Try using cargo binstall for mdbook

* Improve indentation

* Fix note rendering

* Use alerts for GC note

* Remove duplicated section

* Quote test filters

---------

Co-authored-by: Till Schneidereit <till@tillschneidereit.net>

Author: andreiltd

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Deploy mdbook documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      docs-changed: ${{ steps.filter.outputs.docs == 'true' }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 #v3.0.2
+        id: filter
+        with:
+          filters: |
+            docs: docs/**
+
+  deploy:
+    needs: [changes]
+    if: ${{ !contains(needs.changes.outputs.docs-changed, '[]') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@8aac5aa2bf0dfaa2863eccad9f43c68fe40e5ec8 # v1.14.1
+
+      - name: Install mdbook tools
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+        run: |
+          cargo binstall --no-confirm mdbook@0.4.48
+          cargo binstall --no-confirm mdbook-alerts@0.7.0
+          cargo binstall --no-confirm mdbook-linkcheck@0.7.7
+
+      - name: Build mdbook
+        working-directory: ./docs
+        run: mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book/html
+          keep_files: true

.github/workflows/main.yml

@@ -5,6 +5,9 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
 defaults:
   run:
     shell: bash

ADOPTERS.md

@@ -1,10 +1,10 @@
 # StarlingMonkey Adopters
 
-_If you are using StarlingMonkey in production at your organization, please add your company name to this list.
-The list is in alphabetical order._
+_If you are using StarlingMonkey in production at your organization, please add your company name to
+this list. The list is in alphabetical order._
 
-| Organization | Contact | Status | Description of Use |
-| - | - | - | - |
-| [Fastly](https://www.fastly.com) | [@guybedford](https://github.com/guybedford) | ![production](https://img.shields.io/badge/-production-blue?style=flat) | Fastly's [JS SDK](https://github.com/fastly/js-compute-runtime) for Compute at edge is powered by StarlingMonkey. |
+| Organization                        | Contact                                            | Status                                                                  | Description of Use                                                                                                                                              |
+| ----------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Fastly](https://www.fastly.com)    | [@guybedford](https://github.com/guybedford)       | ![production](https://img.shields.io/badge/-production-blue?style=flat) | Fastly's [JS SDK](https://github.com/fastly/js-compute-runtime) for Compute at edge is powered by StarlingMonkey.                                               |
 | [Fermyon](https://www.fermyon.com/) | [@tschneidereit](https://github.com/tschneidereit) | ![production](https://img.shields.io/badge/-production-blue?style=flat) | [Fermyon Spin](https://www.fermyon.com/spin) supports serverless Wasm apps, using StarlingMonkey for its [Spin JS SDK](https://github.com/fermyon/spin-js-sdk). |
-| [Riza](https://riza.io/) | [@kyleconroy](https://github.com/kyleconroy) | ![production](https://img.shields.io/badge/-production-blue?style=flat) | The [Riza Code Interpreter API](https://docs.riza.io) relies on StarlingMonkey for isolated JavaScript execution. |
+| [Riza](https://riza.io/)            | [@kyleconroy](https://github.com/kyleconroy)       | ![production](https://img.shields.io/badge/-production-blue?style=flat) | The [Riza Code Interpreter API](https://docs.riza.io) relies on StarlingMonkey for isolated JavaScript execution.                                               |

AUTHORS.md

@@ -1,3 +1,5 @@
-The portions of this code found in the initial commit are Copyright © 2021-2023 Fastly Inc. and contributors to Fastly's [js-compute-runtime project](https://github.com/fastly/js-compute-runtime/).
+The portions of this code found in the initial commit are Copyright © 2021-2023 Fastly Inc. and
+contributors to Fastly's
+[js-compute-runtime project](https://github.com/fastly/js-compute-runtime/).
 
 Changes following that initial commit are Copyright © the respective contributors.