doc: migration of tact-docs to this repo and to Starlight framework (…

…#880)

* feat: adjusted styles, added fonts and styles for KaTeX

* feat: configuration of docs

* feat: grammars for code highlighting and an impromptu plugin for inline code highlighting

A single-file rehype plugin, which adds inline code highlighting. Works
best for dark theme now, will be improved in the future for better
support of light theme

* feat(CI): testing and deployment workflows

The deployment one can be slightly adjusted to allow deployments on each
merge to master. For actual deployments, we've got to setup GitHub Pages
here and disable them in `tact-docs` repo

.eslintignore

@@ -7,4 +7,5 @@ src/func/funcfiftlib.js
 src/grammar/grammar.ohm*.ts
 src/grammar/grammar.ohm*.js
 jest.setup.js
-jest.teardown.js
+jest.teardown.js
+/docs

.github/PULL_REQUEST_TEMPLATE/code-quality.md

@@ -3,7 +3,7 @@ IMPORTANT:
 If your PR doesn't close a particular issue, please, create the issue first and describe the whole context: what you're adding/changing and why you're doing so. And only then open the Pull Request, which would close that issue!
 
 IMPORTANT:
-In general, the Tact team does not accept refactorings from external contributors unless those were previously discussed and you the green light to do change things without adding new functionality or fixing something broken. Language features, bugfixes, doc improvements are more than welcome!
+In general, the Tact team does not accept refactorings from external contributors unless those were previously discussed and you've got the green light to change things without adding new functionality or to fix something broken. Language features, bugfixes, doc improvements are more than welcome!
 -->
 
 ## Issue

.github/PULL_REQUEST_TEMPLATE/language-feature.md

@@ -10,7 +10,7 @@ Closes #number.
 ## Checklist
 
 - [ ] I have updated CHANGELOG.md
-- [ ] I have documented my contribution in Tact Docs: https://github.com/tact-lang/tact-docs/pull/PR-NUMBER
+- [ ] I have documented my contribution in `docs/` and made the build locally
 - [ ] I have added tests to demonstrate the contribution is correctly implemented: this usually includes both positive and negative tests, showing the happy path(s) and featuring intentionally broken cases
 - [ ] I have run all the tests locally and no test failure was reported
 - [ ] I have run the linter, formatter and spellchecker

.github/workflows/tact-docs-prod.yml

@@ -0,0 +1,52 @@
+# Deploy to GitHub Pages (production)
+name: Build and deploy docs/ to GitHub Pages
+
+on:
+  # For new release tags pushed into the repository
+  # The check for the 'main' branch is done on the job level
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+
+  # Allows to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow simultaneous checks
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+# Allow this job to clone the repo and create a page deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        # with:
+        #   fetch-depth: 0
+      - name: Install, build and store site artifact
+        uses: withastro/action@v3
+        with:
+          path: docs
+          node-version: 22
+          # stores the artifact in docs/dist/
+
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        # takes the artifact from docs/dist/

.github/workflows/tact-docs-test.yml

@@ -0,0 +1,41 @@
+# To not merge, if build fails
+name: Test docs/ build
+
+on:
+  # For new PRs, or those who are ready and/or request a review
+  pull_request:
+    types:
+      [
+        "opened",
+        "edited",
+        "reopened",
+        "synchronize",
+        "ready_for_review",
+        "review_requested",
+      ]
+    branches: ["main"]
+    # Only start the workflow if anything inside the docs has changed
+    paths: ["docs/**"]
+
+  # Allows to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow simultaneous checks
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        # with:
+        #   fetch-depth: 0
+      - name: Install, build and store site artifact
+        uses: withastro/action@v3
+        with:
+          path: docs
+          node-version: 22

.npmignore

@@ -0,0 +1 @@
+/docs

.prettierignore

@@ -1,8 +1,8 @@
 /dist
-
 /src/func/funcfiftlib.js
 /src/func/funcfiftlib.wasm.js
 /src/grammar/grammar.ohm-bundle.d.ts
 /src/grammar/grammar.ohm-bundle.js
 /src/imports/stdlib.ts
 /grammar
+/docs

.yarnignore

@@ -0,0 +1 @@
+/docs

cspell.json

@@ -147,6 +147,7 @@
     "src/test/compilation-fail/fail-const-eval.spec.ts",
     "src/test/e2e-emulated/getter-names-conflict.spec.ts",
     "src/test/exit-codes/contracts/compute-phase-errors.tact",
-    "stdlib/stdlib.fc"
+    "stdlib/stdlib.fc",
+    "/docs"
   ]
 }

docs/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{mdx,md}]
+indent_style = space
+indent_size = 2

docs/.gitignore

@@ -0,0 +1,30 @@
+# build output
+dist/
+out/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+package-lock.json
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# editors
+.vscode/
+.idea/
+.helix/
+.vim/
+.nvim/
+.gitpod.yml

docs/README.md

@@ -0,0 +1,110 @@
+
+<img src="public/banner.jpeg">
+
+# Welcome to ⚡ Tact Documentation
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+Hello there! This is the source for the Tact language documentation.
+
+Latest docs are always available at: [docs.tact-lang.org](https://docs.tact-lang.org).
+
+Our goal here is to create a welcoming and rich resource that benefits all Tact developers, from beginners to experts.
+
+## 🌟 Join the Tact community
+
+Tact is not just a technology; it's a growing community of developers like you! Whether you are just starting out or have tons of experience, your contributions are valuable.
+
+Here's how you can contribute:
+
+- Organize or clarify information 📝
+- Make Pull Requests to improve the code or docs 🚀
+- Share tutorials, guides, and articles 📚
+
+Join our community chat to stay updated and collaborate: [Tact Telegram community](https://t.me/tactlang)
+
+## 🤔 How can you contribute?
+
+Contributing is not just encouraged, it's easy!
+
+If you've solved a challenging problem or found a better way to explain a complex topic, share it:
+
+— Got an idea? [Open an issue](https://github.com/tact-lang/tact/issues/new).
+— Ready to contribute? [Setup the dev environment](#setup-your-development-environment).
+
+### ⚙️ Setup your development environment
+
+Before you submit your amazing contributions, ensure they work seamlessly.
+
+#### 🌩️ Quick cloud setup
+
+Use Gitpod for a hassle-free cloud-based IDE experience:
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/tact-lang/tact-docs)
+
+#### 🏠 Local setup
+
+1. Clone this GitHub repository.
+2. Make sure to have the latest version of [Node.js LTS](https://nodejs.org/en/download/) installed.
+3. Open your terminal in the project directory.
+4. Install dependencies without modifying the `yarn.lock`:
+
+   ```
+   yarn deps
+   ```
+
+5. Start your local development server:
+
+   ```
+   yarn dev
+   ```
+
+This will open a new browser window displaying your local version of the documentation. Most updates are automatically reflected.
+
+### 🚀 Project Structure
+
+Inside of this Astro + Starlight project, you'll see the following folders and files (besides others):
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/     ← HERE ARE ALL THE TACT DOCUMENTATION PAGES
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+└── cspell.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. The Tact docs use `.mdx` files only.
+
+Images can be added to `src/assets/` and embedded in MDX files with a relative link. Static assets, like favicons, can be placed in the `public/` directory.
+
+It's recommended that local images are kept in `src/` whenever possible, so that Astro can transform, optimize and bundle them. Files in the `public/` directory are always served or copied into the build folder as-is, with no processing, and are publicly available by a direct link.
+
+The local images stored in `src/` can be used by all files in the project: `.astro`, `.md`, `.mdx`, `.mdoc`, and other UI frameworks (if any). Images can be stored in any folder, including alongside your content.
+
+### 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action
+| :------------------------ | :-----
+| `yarn deps`               | Installs dependencies.
+| `yarn dev`                | Starts local dev server at `localhost:4321`.
+| `yarn build`              | Build your production site to `./dist/`. Runs CSpell and also validates all the internal links.
+| `yarn preview`            | Preview your build locally, before deploying.
+| `yarn astro ...`          | Run CLI commands like `astro add`, `astro check`, etc.
+| `yarn astro -- --help`    | Get help using the Astro CLI.
+
+### 👀 Want to learn more about the framework behind Tact docs?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+
+## License 📄
+
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)