feat: add docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Docs
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  deploy:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build
+        working-directory: docs
+        run: npm run build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build

.gitignore

@@ -4,3 +4,5 @@ build/
 a.out
 vgcore.*
 inbox.txt.tuxedo-lock
+docs/node_modules
+docs/build

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/getting-started.md

@@ -0,0 +1,79 @@
+---
+id: getting-started
+title: Getting Started
+sidebar_position: 2
+---
+
+# Getting Started
+
+## Dependencies
+
+To build the Cleaf compiler:
+
+- `gcc`
+
+To compile `.clf` source files with the resulting binary:
+
+- `nasm`
+- `ld` (from binutils)
+
+## Building the compiler
+
+```sh
+git clone https://github.com/viastolfi/cleaf.git
+cd cleaf
+make
+```
+
+This produces `./build/cleaf`.
+
+## Compiling a Cleaf program
+
+```sh
+./build/cleaf <source.clf>           # compile to ./a.out
+./build/cleaf <source.clf> -o <out>  # compile with a custom output name
+```
+
+### Debug flags
+
+```sh
+./build/cleaf <source.clf> -v        # show each compilation phase and its result
+./build/cleaf <source.clf> -V        # same as -v, and dump AST, HIR, and generated assembly
+```
+
+## Your first program
+
+Create a file called `hello.clf`:
+
+```cleaf
+fn main(): int {
+    return 0;
+}
+```
+
+Compile and run it:
+
+```sh
+./build/cleaf hello.clf -o hello
+./hello
+echo $?   # prints 0
+```
+
+## A more complete example
+
+```cleaf
+fn add(int a, int b): int {
+    return a + b;
+}
+
+fn main(): int {
+    var x = add(3, 4);
+    return x;
+}
+```
+
+```sh
+./build/cleaf example.clf -o example
+./example
+echo $?   # prints 7
+```

docs/docs/intro.mdx

@@ -0,0 +1,54 @@
+---
+id: intro
+title: Introduction
+sidebar_position: 1
+slug: /intro
+---
+
+# Introduction
+
+:::caution Work in progress
+Cleaf is under active development. The language and compiler are not feature-complete.
+Breaking changes to the syntax or pipeline are expected.
+:::
+
+**Cleaf** is a small, statically typed compiled language targeting x86-64 Linux.
+Source files use the `.clf` extension.
+
+The compiler is written in C and produces native executables via **NASM** and the system linker — no LLVM, no runtime, no garbage collector (yet).
+
+## Motivation
+
+Cleaf is a personal project to explore compiler construction from scratch, covering the full pipeline from lexing to native code generation. The language is intentionally simple and C-like, with a focus on clean, readable syntax compiled directly to machine code.
+
+## Compilation pipeline
+
+```
+source (.clf) → lexer → parser → semantic analysis → HIR lowering → codegen → NASM → ld → executable
+```
+
+## Feature status
+
+| Feature | Status |
+|---|---|
+| Lexer | ✅ |
+| Parser | ✅ |
+| Semantic analysis | ✅ |
+| HIR lowering | ✅ |
+| x86-64 code generation | ✅ |
+| `int`, `u8`, `u16`, `u64` types | ✅ |
+| Type inference (`var`) | ✅ |
+| Constant variables | ✅ |
+| Functions with typed params | ✅ |
+| Structs & designated initializers | ✅ |
+| `if` / `else` | ✅ |
+| `while` / `for` | ✅ |
+| Arithmetic & comparisons | ✅ |
+| Unary operators (`++`, `--`, `-`, `!`) | ✅ |
+| Function calls | ✅ |
+| Inline assembly (`asm`) | ✅ |
+| Arrays | ❌ Planned |
+| Floats / strings / booleans | ❌ Planned |
+| Multiple source files | ❌ Planned |
+| Standard library | ❌ Planned |
+| Memory model | ❌ Not yet decided |

docs/docs/language/comments.md

@@ -0,0 +1,41 @@
+---
+id: comments
+title: Comments
+sidebar_position: 8
+---
+
+# Comments
+
+Cleaf supports two comment styles, identical to C.
+
+## Single-line comments
+
+Start with `//` and extend to the end of the line.
+
+```cleaf
+// This is a single-line comment
+fn main(): int {
+    var x = 10;  // inline comment
+    return x;
+}
+```
+
+## Multi-line comments
+
+Delimited by `/*` and `*/`. Can span multiple lines.
+
+```cleaf
+/*
+ * This function computes
+ * the sum of two integers.
+ */
+fn add(int a, int b): int {
+    return a + b;
+}
+```
+
+Multi-line comments do **not** nest:
+
+```cleaf
+/* outer /* inner */ this is still inside the outer comment */
+```

docs/docs/language/control-flow.md

@@ -0,0 +1,106 @@
+---
+id: control-flow
+title: Control Flow
+sidebar_position: 5
+---
+
+# Control Flow
+
+## if / else
+
+```cleaf
+if (<condition>) {
+    // executed when condition is true
+}
+
+if (<condition>) {
+    // then branch
+} else {
+    // else branch
+}
+```
+
+### Example
+
+```cleaf
+fn classify(int n): int {
+    if (n > 0) {
+        return 1;
+    } else {
+        return 0;
+    }
+}
+```
+
+Variables declared inside an `if` block are scoped to that block.
+
+## while
+
+Executes the body repeatedly as long as the condition is true.
+
+```cleaf
+while (<condition>) {
+    // body
+}
+```
+
+### Example
+
+```cleaf
+fn count_down(int n): int {
+    while (n > 0) {
+        n = n - 1;
+    }
+    return n;
+}
+```
+
+## for
+
+The `for` loop has three parts: an initializer, a condition, and a loop expression (typically an increment).
+
+```cleaf
+for (<init>; <condition>; <loop>) {
+    // body
+}
+```
+
+- `<init>` can be a variable declaration (`var i = 0` or `int i = 0`) or an expression.
+- `<condition>` is evaluated before each iteration; the loop exits when it becomes false.
+- `<loop>` is evaluated after each iteration (before re-checking the condition).
+
+### Example
+
+```cleaf
+fn sum(int n): int {
+    var total = 0;
+    for (var i = 0; i < n; ++i) {
+        total = total + i;
+    }
+    return total;
+}
+```
+
+Variables declared in the init expression are scoped to the loop body.
+
+## Nested control flow
+
+Control flow statements can be nested freely:
+
+```cleaf
+fn main(): int {
+    var result = 0;
+
+    for (var i = 0; i < 10; ++i) {
+        if (i == 5) {
+            result = result + 1;
+        }
+    }
+
+    while (result > 0) {
+        result = result - 1;
+    }
+
+    return result;
+}
+```