Moved all docs from ./docs/ to ./web/documentation/ to be available on the website. No code changes. (0.40.5)

docs/README.md

@@ -1,58 +0,0 @@
-# Fun Documentation Index
-
-This file serves as an index of the documents in this directory. Links are relative and can be opened directly on Git hosting or locally.
-
-## Overview
-
-- [handbook.md](./handbook.md) - Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview.
-- [types.md](./types.md) - Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes.
-- [numbers.md](./numbers.md) - Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns.
-- [strings.md](./strings.md) - Working with strings: literals/escaping, concatenation, substr/find, split, and conversions.
-- [arrays.md](./arrays.md) - Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms.
-- [maps.md](./maps.md) - Working with maps: construction, lookup/update, merging, iteration, and common patterns.
-- [includes.md](./includes.md) - Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with `as`.
-- [repl.md](./repl.md) - REPL guide: how to build/launch, editing and history, completions, REPL-on-error, and tips.
-- [opcodes.md](./opcodes.md) - VM opcodes overview grouped by domain with brief behavior/stack notes.
-- [internals.md](./internals.md) - Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch.
-- [rust.md](./rust.md) - Writing Rust-backed opcodes and wiring them into the C VM; build/setup notes.
-- [examples.md](./examples.md) - How to run the examples and the interactive showcase script, with environment tips.
-- [testing.md](./testing.md) - How to build and run tests/targets with CMake/CTest, and where to add new tests.
-- [troubleshooting.md](./troubleshooting.md) - Common issues and quick fixes for build, includes, and REPL usage.
-
-## New and supplemental guides
-
-- [build.md](./build.md) - How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST, FUN_WITH_OPENSSL).
-- [cli.md](./cli.md) - Command-line usage of the `fun` executable: synopsis, options, exit codes, includes and library paths.
-- [fun.md](./fun.md) - Full usage guide for the `fun` executable: invocation patterns, REPL, env vars, include paths, examples, and install locations.
-- [asyncio.md](./asyncio.md) - Async I/O primitives and patterns: non-blocking sockets, fd polling, examples, and best practices.
-- [funstx.md](./funstx.md) - Syntax checker for .fun files with optional --fix auto-corrections; usage, exit codes, and limitations.
-- [contributing.md](./contributing.md) - How to contribute: project structure, coding style, running tests, and PR guidelines.
-- [style-guide.md](./style-guide.md) - Coding conventions for C and Fun (indentation, naming, idioms).
-- [stdlib.md](./stdlib.md) - Overview of the standard library modules under ./lib with one-line summaries.
-- [embedding.md](./embedding.md) - Embedding the VM from C/Rust, lifecycle, and host integration tips.
-- [errors-and-diagnostics.md](./errors-and-diagnostics.md) - Understanding parser/runtime errors and enabling diagnostics.
-- [performance.md](./performance.md) - Build/runtime tuning tips and patterns for better performance.
-- [security-and-sandboxing.md](./security-and-sandboxing.md) - Trust boundaries, I/O expectations, and capability restrictions.
-- [faq.md](./faq.md) - Frequently asked questions and quick answers.
-- [website.md](./website.md) - Documentation for the [fun-lang.xyz](https://fun-lang.xyz) website in the `./web/` directory.
-- [writing-tests.md](./writing-tests.md) - How to author new tests for Fun and opcode components.
-- [bytecode-format.md](./bytecode-format.md) - Reference for the bytecode format (split out from internals for convenience).
-- [roadmap.md](./roadmap.md) - High-level direction, planned features, and pointers to issues.
-
-## Examples
-
- - [examples/README.md](./examples/README.md) - Catalog of all example scripts under ./examples/: what each area contains, how to run them, required env vars, and extension requirements.
-
-## External extensions
-
-Documentation for optional, build-time selectable integrations lives in [external/](./external/):
-
-- [Index of extensions](./external/README.md)
- - Highlights: [cURL](./external/curl.md), [INI](./external/ini.md), [JSON](./external/json.md), [XML (libxml2)](./external/xml2.md), [SQLite](./external/sqlite.md), [PCRE2](./external/pcre2.md), [PC/SC](./external/pcsc.md), [OpenSSL](./external/openssl.md)
-
-## Tips
-
-- When building from the repo without installing, set `FUN_LIB_DIR` to the local `./lib` directory so examples and the REPL can locate the stdlib.
-- For a broader project overview and quickstart, see the repository root [README.md](../README.md).
-- Crypto examples:
-  - If built with `-DFUN_WITH_OPENSSL=ON`, try `examples/crypto/openssl_md5.fun`.

docs/examples/builtins_maps_and_more.md

@@ -1,12 +0,0 @@
-# builtins_maps_and_more.fun — overview
-
-What it shows
-- Exploring built‑ins while working with maps and related data structures.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/builtins_maps_and_more.fun
-- Or: fun examples/builtins_maps_and_more.fun
-
-Notes
-- Open the .fun file to see the exact behaviors and printed output.

docs/examples/byte_for_demo.md

@@ -1,9 +0,0 @@
-# byte_for_demo.fun — overview
-
-What it shows
-- Iterating bytes with a for-loop; indexing and printing byte values.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/byte_for_demo.fun
-- Or: fun examples/byte_for_demo.fun

docs/examples/byte_overflow_try_catch.md

@@ -1,9 +0,0 @@
-# byte_overflow_try_catch.fun — overview
-
-What it shows
-- Error handling around byte/integer overflow using try/catch.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/byte_overflow_try_catch.fun
-- Or: fun examples/byte_overflow_try_catch.fun

docs/examples/cast_demo.md

@@ -1,9 +0,0 @@
-# cast_demo.fun — overview
-
-What it shows
-- Conversions and casting helpers; demonstrates changing between numeric and string types safely.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/cast_demo.fun
-- Or: fun examples/cast_demo.fun

docs/examples/class_constructor.md

@@ -1,9 +0,0 @@
-# class_constructor.fun — overview
-
-What it shows
-- Class basics and constructor behavior; initializing fields and using methods.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/class_constructor.fun
-- Or: fun examples/class_constructor.fun

docs/examples/class_test.md

@@ -1,12 +0,0 @@
-# class_test.fun — overview
-
-What it shows
-- Simple class usage and method invocation; small sanity checks around classes.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/class_test.fun
-- Or: fun examples/class_test.fun
-
-Notes
-- Open the script to see the exact behavior and outputs.

docs/examples/class_without_object.md

@@ -1,9 +0,0 @@
-# class_without_object.fun — overview
-
-What it shows
-- Class features that can be used without creating an instance (static-like usage patterns).
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/class_without_object.fun
-- Or: fun examples/class_without_object.fun

docs/examples/classes_demo.md

@@ -1,9 +0,0 @@
-# classes_demo.fun — overview
-
-What it shows
-- Class basics and usage: defining classes, instantiating objects, calling methods.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/classes_demo.fun
-- Or: fun examples/classes_demo.fun

docs/examples/cli_argv_dump.md

@@ -1,9 +0,0 @@
-# cli_argv_dump.fun — overview
-
-What it shows
-- Prints argv/argc handling to demonstrate CLI arguments parsing at a low level.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/cli_argv_dump.fun --foo bar 123
-- Or: fun examples/cli_argv_dump.fun --foo bar 123

docs/examples/conversions_showcase.md

@@ -1,9 +0,0 @@
-# conversions_showcase.fun — overview
-
-What it shows
-- Numbers, strings, and bytes conversions; typical idioms and edge cases.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/conversions_showcase.fun
-- Or: fun examples/conversions_showcase.fun

docs/examples/cpp_add.md

@@ -1,12 +0,0 @@
-# cpp_add.fun — overview
-
-What it shows
-- Calling into the optional C++ extension from Fun.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/cpp_add.fun
-- Or: fun examples/cpp_add.fun
-
-Notes
-- Requires the optional C++ extension to be enabled in your build; otherwise this example may be unavailable.

docs/examples/data/htdocs/counter.md

@@ -1,17 +0,0 @@
-# counter.fun (CGI)
-
-- Location: examples/data/htdocs/counter.fun
-- Category: CGI script used by HTTP server examples
-
-Description
-- Simple stateful counter example for CGI; demonstrates reading and updating a value across requests (implementation details in script).
-
-How to run
-- Through one of the HTTP server examples, e.g.:
-  - export FUN_LIB_DIR="./lib"
-  - export FUN_EXEC="./build_debug/fun"
-  - ./build_debug/fun examples/net/http_server_cgi.fun
-  - Open: http://127.0.0.1:8080/counter.fun
-
-See also
-- docs/examples/httpserver.md (deep-dive)

docs/examples/data/htdocs/form_post.md

@@ -1,17 +0,0 @@
-# form_post.fun (CGI)
-
-- Location: examples/data/htdocs/form_post.fun
-- Category: CGI script used by HTTP server examples
-
-Description
-- Demonstrates handling of POST form data via the CGI interface.
-
-How to run
-- Through one of the HTTP server examples, e.g.:
-  - export FUN_LIB_DIR="./lib"
-  - export FUN_EXEC="./build_debug/fun"
-  - ./build_debug/fun examples/net/http_server_cgi.fun
-  - Submit a form to: http://127.0.0.1:8080/form_post.fun
-
-See also
-- docs/examples/httpserver.md (deep-dive)

docs/examples/data/htdocs/hello.md

@@ -1,17 +0,0 @@
-# hello.fun (CGI)
-
-- Location: examples/data/htdocs/hello.fun
-- Category: CGI script used by HTTP server examples
-
-Description
-- Simple CGI .fun script that prints a greeting, optionally using query parameters (e.g., ?name=Fun).
-
-How to run
-- Through one of the HTTP server examples, e.g.:
-  - export FUN_LIB_DIR="./lib"
-  - export FUN_EXEC="./build_debug/fun"
-  - ./build_debug/fun examples/net/http_server_cgi.fun
-  - Open: http://127.0.0.1:8080/hello.fun?name=Fun
-
-See also
-- docs/examples/httpserver.md (deep-dive)

docs/examples/data/htdocs/info.md

@@ -1,17 +0,0 @@
-# info.fun (CGI)
-
-- Location: examples/data/htdocs/info.fun
-- Category: CGI script used by HTTP server examples
-
-Description
-- CGI script that prints request/environment information, useful for debugging CGI variables.
-
-How to run
-- Through one of the HTTP server examples, e.g.:
-  - export FUN_LIB_DIR="./lib"
-  - export FUN_EXEC="./build_debug/fun"
-  - ./build_debug/fun examples/net/http_server_cgi.fun
-  - Open: http://127.0.0.1:8080/info.fun
-
-See also
-- docs/examples/httpserver.md (deep-dive)

docs/examples/data/htdocs/json_like_api.md

@@ -1,17 +0,0 @@
-# json_like_api.fun (CGI)
-
-- Location: examples/data/htdocs/json_like_api.fun
-- Category: CGI script used by HTTP server examples
-
-Description
-- Demonstrates returning JSON-like output from a CGI endpoint.
-
-How to run
-- Through one of the HTTP server examples, e.g.:
-  - export FUN_LIB_DIR="./lib"
-  - export FUN_EXEC="./build_debug/fun"
-  - ./build_debug/fun examples/net/http_server_cgi.fun
-  - Open: http://127.0.0.1:8080/json_like_api.fun
-
-See also
-- docs/examples/httpserver.md (deep-dive)

docs/examples/data/htdocs/redirect.md

@@ -1,17 +0,0 @@
-# redirect.fun (CGI)
-
-- Location: examples/data/htdocs/redirect.fun
-- Category: CGI script used by HTTP server examples
-
-Description
-- Demonstrates issuing HTTP redirects from a CGI script (setting Status and Location headers).
-
-How to run
-- Through one of the HTTP server examples, e.g.:
-  - export FUN_LIB_DIR="./lib"
-  - export FUN_EXEC="./build_debug/fun"
-  - ./build_debug/fun examples/net/http_server_cgi.fun
-  - Open: http://127.0.0.1:8080/redirect.fun
-
-See also
-- docs/examples/httpserver.md (deep-dive)

docs/examples/datetime_basic.md

@@ -1,9 +0,0 @@
-# datetime_basic.fun — overview
-
-What it shows
-- Basic time/date helpers and formatting.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/datetime_basic.fun
-- Or: fun examples/datetime_basic.fun

docs/examples/datetime_extended.md

@@ -1,9 +0,0 @@
-# datetime_extended.fun — overview
-
-What it shows
-- Extended datetime helpers: parsing, arithmetic, timers, and formatting variants.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/datetime_extended.fun
-- Or: fun examples/datetime_extended.fun

docs/examples/datetime_timer.md

@@ -1,9 +0,0 @@
-# datetime_timer.fun — overview
-
-What it shows
-- Measuring elapsed time and simple timers using datetime helpers.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/datetime_timer.fun
-- Or: fun examples/datetime_timer.fun

docs/examples/echo_example.md

@@ -1,9 +0,0 @@
-# echo_example.fun — overview
-
-What it shows
-- Simple echo of input/args; prints back what you type or pass as arguments.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/echo_example.fun hello world
-- Or: fun examples/echo_example.fun hello world

docs/examples/env_all.md

@@ -1,9 +0,0 @@
-# env_all.fun — overview
-
-What it shows
-- Reading and listing environment variables.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/env_all.fun
-- Or: fun examples/env_all.fun

docs/examples/error_handling.md

@@ -1,9 +0,0 @@
-# error_handling.fun — overview
-
-What it shows
-- Error patterns and handling strategies using try/catch/finally.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/error_handling.fun
-- Or: fun examples/error_handling.fun

docs/examples/expressions_test.md

@@ -1,9 +0,0 @@
-# expressions_test.fun — overview
-
-What it shows
-- Operator precedence and expression grouping tests/demonstrations.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/expressions_test.fun
-- Or: fun examples/expressions_test.fun

docs/examples/features.md

@@ -1,9 +0,0 @@
-# features.fun — overview
-
-What it shows
-- Grab bag of language features in a single script.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/features.fun
-- Or: fun examples/features.fun

docs/examples/file_print_for_file_line_by_line.md

@@ -1,9 +0,0 @@
-# file_print_for_file_line_by_line.fun — overview
-
-What it shows
-- Iterate a file line-by-line and print each line; basic file IO idioms.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/file_print_for_file_line_by_line.fun path/to/file.txt
-- Or: fun examples/file_print_for_file_line_by_line.fun path/to/file.txt

docs/examples/floats.md

@@ -1,9 +0,0 @@
-# floats.fun — overview
-
-What it shows
-- Floating point operations and formatting details.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/floats.fun
-- Or: fun examples/floats.fun

docs/examples/for_range_test.md

@@ -1,9 +0,0 @@
-# for_range_test.fun — overview
-
-What it shows
-- Ranges and loops; iterating numeric ranges and verifying bounds.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/for_range_test.fun
-- Or: fun examples/for_range_test.fun

docs/examples/functions_test.md

@@ -1,9 +0,0 @@
-# functions_test.fun — overview
-
-What it shows
-- Functions, closures, and return behavior; call semantics basics.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/functions_test.fun
-- Or: fun examples/functions_test.fun

docs/examples/have_fun.md

@@ -1,9 +0,0 @@
-# have_fun.fun — overview
-
-What it shows
-- Playful demo showing off small language tricks.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/have_fun.fun
-- Or: fun examples/have_fun.fun

docs/examples/have_fun_function.md

@@ -1,9 +0,0 @@
-# have_fun_function.fun — overview
-
-What it shows
-- A playful function-centric demo; small utility behaviors.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/have_fun_function.fun
-- Or: fun examples/have_fun_function.fun

docs/examples/hex_example.md

@@ -1,9 +0,0 @@
-# hex_example.fun — overview
-
-What it shows
-- Hex encode/decode helpers; working with hexadecimal representations.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/hex_example.fun
-- Or: fun examples/hex_example.fun

docs/examples/if_else_test.md

@@ -1,9 +0,0 @@
-# if_else_test.fun — overview
-
-What it shows
-- Control flow with if/else; branching and comparisons.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/if_else_test.fun
-- Or: fun examples/if_else_test.fun

docs/examples/include_lib.md

@@ -1,9 +0,0 @@
-# include_lib.fun — overview
-
-What it shows
-- Including modules from the standard library path using #include <...>.
-
-How to run
-- export FUN_LIB_DIR="./lib"  # ensure stdlib is discoverable
-- ./build_debug/fun examples/include_lib.fun
-- Or: fun examples/include_lib.fun

docs/examples/include_local.md

@@ -1,9 +0,0 @@
-# include_local.fun — overview
-
-What it shows
-- Including local files relative to the script and reusing helpers.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/include_local.fun
-- Or: fun examples/include_local.fun

docs/examples/include_local_util.md

@@ -1,9 +0,0 @@
-# include_local_util.fun — overview
-
-What it shows
-- Local include mechanics with a small utility module.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/include_local_util.fun
-- Or: fun examples/include_local_util.fun

docs/examples/inheritance_demo.md

@@ -1,9 +0,0 @@
-# inheritance_demo.fun — overview
-
-What it shows
-- Simple class inheritance and method overriding examples.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/inheritance_demo.fun
-- Or: fun examples/inheritance_demo.fun

docs/examples/loops_break_continue.md

@@ -1,9 +0,0 @@
-# loops_break_continue.fun — overview
-
-What it shows
-- Loop control: break and continue; demonstrating control flow within loops.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/loops_break_continue.fun
-- Or: fun examples/loops_break_continue.fun

docs/examples/maps.md

@@ -1,9 +0,0 @@
-# maps.fun — overview
-
-What it shows
-- Working with maps: creation, indexing, iteration, and typical idioms.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/maps.fun
-- Or: fun examples/maps.fun

docs/examples/match.md

@@ -1,9 +0,0 @@
-# match.fun — overview
-
-What it shows
-- Pattern matching constructs and examples of branching by value/shape.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/match.fun
-- Or: fun examples/match.fun

docs/examples/namespaced_mod.md

@@ -1,9 +0,0 @@
-# namespaced_mod.fun — overview
-
-What it shows
-- Namespaced includes and using the "as" aliasing pattern for modules.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/namespaced_mod.fun
-- Or: fun examples/namespaced_mod.fun

docs/examples/nested_loops.md

@@ -1,9 +0,0 @@
-# nested_loops.fun — overview
-
-What it shows
-- Control flow with nested loops; inner/outer loop coordination.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/nested_loops.fun
-- Or: fun examples/nested_loops.fun

docs/examples/net/http_static_server.md

@@ -1,20 +0,0 @@
-# http_static_server.fun
-
-- Location: examples/net/http_static_server.fun
-- Category: Networking / Sockets
-
-Description
-- Minimal static HTTP server implemented directly on sockets. Accepts connections and always returns a small HTML page.
-
-How to run
-- From the repository root:
-  - export FUN_LIB_DIR="./lib"
-  - ./build_debug/fun examples/net/http_static_server.fun
-  - Then open http://127.0.0.1:8088/
-
-Requirements
-- Uses core IO/socket stdlib (io/socket.fun). No optional extensions required.
-
-See also
-- docs/examples/README.md
-- docs/examples/httpserver.md (deep-dive over HTTP servers)

docs/examples/objects_basic.md

@@ -1,9 +0,0 @@
-# objects_basic.fun — overview
-
-What it shows
-- OO basics: defining objects, fields, and invoking methods.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/objects_basic.fun
-- Or: fun examples/objects_basic.fun

docs/examples/objects_more.md

@@ -1,9 +0,0 @@
-# objects_more.fun — overview
-
-What it shows
-- Additional object patterns: composition, methods, and utilities.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/objects_more.fun
-- Or: fun examples/objects_more.fun

docs/examples/os_env.md

@@ -1,9 +0,0 @@
-# os_env.fun — overview
-
-What it shows
-- Reading and writing environment variables from the operating system.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/os_env.fun
-- Or: fun examples/os_env.fun

docs/examples/process_example.md

@@ -1,9 +0,0 @@
-# process_example.fun — overview
-
-What it shows
-- Spawning and capturing subprocess output; simple process management.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/process_example.fun
-- Or: fun examples/process_example.fun

docs/examples/progress.md

@@ -1,9 +0,0 @@
-# progress.fun — overview
-
-What it shows
-- Simple progress display in the terminal.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/progress.fun
-- Or: fun examples/progress.fun

docs/examples/progress_inline.md

@@ -1,9 +0,0 @@
-# progress_inline.fun — overview
-
-What it shows
-- Inline progress updates (same line updates) for simple terminal UIs.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/progress_inline.fun
-- Or: fun examples/progress_inline.fun

docs/examples/random_demo.md

@@ -1,9 +0,0 @@
-# random_demo.fun — overview
-
-What it shows
-- Random number generator usage and seeding basics.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/random_demo.fun
-- Or: fun examples/random_demo.fun

docs/examples/random_number_example.md

@@ -1,9 +0,0 @@
-# random_number_example.fun — overview
-
-What it shows
-- Generating random numbers and printing them; small utility demo.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/random_number_example.fun
-- Or: fun examples/random_number_example.fun

docs/examples/regex_demo.md

@@ -1,12 +0,0 @@
-# regex_demo.fun — overview
-
-What it shows
-- Regex helpers usage; simple matching and replacement tasks.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/regex_demo.fun
-- Or: fun examples/regex_demo.fun
-
-Notes
-- Some regex examples depend on the optional PCRE2 extension; enable it in your build to run.

docs/examples/regex_procedural.md

@@ -1,12 +0,0 @@
-# regex_procedural.fun — overview
-
-What it shows
-- Procedural approach to regex work: compiling patterns and iterating matches.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/regex_procedural.fun
-- Or: fun examples/regex_procedural.fun
-
-Notes
-- May require the optional PCRE2 extension in your build.

docs/examples/rust_hello.md

@@ -1,12 +0,0 @@
-# rust_hello.fun — overview
-
-What it shows
-- Using Rust opcodes from Fun (when built with Rust support).
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/rust_hello.fun
-- Or: fun examples/rust_hello.fun
-
-Notes
-- Requires building with FUN_WITH_RUST; otherwise this example will be unavailable.

docs/examples/rust_hello_args.md

@@ -1,12 +0,0 @@
-# rust_hello_args.fun — overview
-
-What it shows
-- Passing arguments into Rust-backed opcodes and handling returns.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/rust_hello_args.fun
-- Or: fun examples/rust_hello_args.fun
-
-Notes
-- Requires building with FUN_WITH_RUST.

docs/examples/rust_hello_args_return.md

@@ -1,12 +0,0 @@
-# rust_hello_args_return.fun — overview
-
-What it shows
-- Demonstrates returning values from Rust-backed opcodes with arguments.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/rust_hello_args_return.fun
-- Or: fun examples/rust_hello_args_return.fun
-
-Notes
-- Requires building with FUN_WITH_RUST.

docs/examples/serial_demo.md

@@ -1,12 +0,0 @@
-# serial_demo.fun — overview
-
-What it shows
-- Serial port access and basic read/write (when available on your system).
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/serial_demo.fun
-- Or: fun examples/serial_demo.fun
-
-Notes
-- Requires serial device access; may depend on platform support and permissions.

docs/examples/short_circuit_test.md

@@ -1,9 +0,0 @@
-# short_circuit_test.fun — overview
-
-What it shows
-- Boolean evaluation order and short-circuit behavior with && and ||.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/short_circuit_test.fun
-- Or: fun examples/short_circuit_test.fun

docs/examples/signed_ints.md

@@ -1,9 +0,0 @@
-# signed_ints.fun — overview
-
-What it shows
-- Signed integer types and operations; ranges and conversions.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/signed_ints.fun
-- Or: fun examples/signed_ints.fun

docs/examples/stdlib_showcase.md

@@ -1,9 +0,0 @@
-# stdlib_showcase.fun — overview
-
-What it shows
-- Sampler of common standard library modules and utilities.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/stdlib_showcase.fun
-- Or: fun examples/stdlib_showcase.fun

docs/examples/strings_test.md

@@ -1,9 +0,0 @@
-# strings_test.fun — overview
-
-What it shows
-- String helpers and edge cases; splitting, joining, trimming, and formatting.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/strings_test.fun
-- Or: fun examples/strings_test.fun

docs/examples/tcp_http_get.md

@@ -1,12 +0,0 @@
-# tcp_http_get.fun — overview
-
-What it shows
-- Manual HTTP client over raw TCP sockets: connect, write request, read response.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/tcp_http_get.fun
-- Or: fun examples/tcp_http_get.fun
-
-Notes
-- Requires network access to the target host used in the script.

docs/examples/tcp_http_get_class.md

@@ -1,12 +0,0 @@
-# tcp_http_get_class.fun — overview
-
-What it shows
-- Manual HTTP client implemented with a small helper class over sockets.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/tcp_http_get_class.fun
-- Or: fun examples/tcp_http_get_class.fun
-
-Notes
-- Requires network access to the target host used in the script.

docs/examples/test_bits.md

@@ -1,9 +0,0 @@
-# test_bits.fun — overview
-
-What it shows
-- Bitwise utilities demonstration (and/or/xor/shifts) and small tests.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_bits.fun
-- Or: fun examples/test_bits.fun

docs/examples/test_dec_to_hex.md

@@ -1,9 +0,0 @@
-# test_dec_to_hex.fun — overview
-
-What it shows
-- Decimal to hexadecimal conversion helper/tests.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_dec_to_hex.fun
-- Or: fun examples/test_dec_to_hex.fun

docs/examples/test_hex_to_dec.md

@@ -1,9 +0,0 @@
-# test_hex_to_dec.fun — overview
-
-What it shows
-- Hexadecimal to decimal conversion helper/tests.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_hex_to_dec.fun
-- Or: fun examples/test_hex_to_dec.fun

docs/examples/test_include.md

@@ -1,9 +0,0 @@
-# test_include.fun — overview
-
-What it shows
-- Small include mechanics test; ensures local and stdlib includes work.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_include.fun
-- Or: fun examples/test_include.fun

docs/examples/test_rol.md

@@ -1,9 +0,0 @@
-# test_rol.fun — overview
-
-What it shows
-- Bit rotation (ROL) helper/tests.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_rol.fun
-- Or: fun examples/test_rol.fun

docs/examples/test_serial.md

@@ -1,12 +0,0 @@
-# test_serial.fun — overview
-
-What it shows
-- Serial port test; opens a port and exchanges a few bytes (when available).
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_serial.fun
-- Or: fun examples/test_serial.fun
-
-Notes
-- Requires serial device access; may depend on platform support and permissions.

docs/examples/test_shl.md

@@ -1,9 +0,0 @@
-# test_shl.fun — overview
-
-What it shows
-- Bit shift left (SHL) helper/tests.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_shl.fun
-- Or: fun examples/test_shl.fun

docs/examples/test_types.md

@@ -1,9 +0,0 @@
-# test_types.fun — overview
-
-What it shows
-- Type checks and simple assertions around type behavior.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_types.fun
-- Or: fun examples/test_types.fun

docs/examples/test_xor.md

@@ -1,9 +0,0 @@
-# test_xor.fun — overview
-
-What it shows
-- Bitwise XOR helper/tests.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/test_xor.fun
-- Or: fun examples/test_xor.fun

docs/examples/thread_class_example.md

@@ -1,9 +0,0 @@
-# thread_class_example.fun — overview
-
-What it shows
-- Threading building blocks using a small thread class; start/join patterns.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/thread_class_example.fun
-- Or: fun examples/thread_class_example.fun

docs/examples/threads_demo.md

@@ -1,9 +0,0 @@
-# threads_demo.fun — overview
-
-What it shows
-- Threading building blocks and concurrent execution demo.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/threads_demo.fun
-- Or: fun examples/threads_demo.fun

docs/examples/try_catch_finally.md

@@ -1,9 +0,0 @@
-# try_catch_finally.fun — overview
-
-What it shows
-- Structured error handling with try/catch/finally blocks.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/try_catch_finally.fun
-- Or: fun examples/try_catch_finally.fun

docs/examples/type_safety.md

@@ -1,9 +0,0 @@
-# type_safety.fun — overview
-
-What it shows
-- Static/dynamic type checks and enforcing type safety in small examples.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/type_safety.fun
-- Or: fun examples/type_safety.fun

docs/examples/type_safety_fails.md

@@ -1,9 +0,0 @@
-# type_safety_fails.fun — overview
-
-What it shows
-- Examples that intentionally violate type expectations to illustrate safety checks.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/type_safety_fails.fun
-- Or: fun examples/type_safety_fails.fun

docs/examples/typeof.md

@@ -1,9 +0,0 @@
-# typeof.fun — overview
-
-What it shows
-- Type inspection using typeof and related helpers.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/typeof.fun
-- Or: fun examples/typeof.fun

docs/examples/typeof_features.md

@@ -1,9 +0,0 @@
-# typeof_features.fun — overview
-
-What it shows
-- A tour of typeof-related features and type introspection helpers.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/typeof_features.fun
-- Or: fun examples/typeof_features.fun

docs/examples/types_integers.md

@@ -1,9 +0,0 @@
-# types_integers.fun — overview
-
-What it shows
-- Integer type families, ranges, and basic operations.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/types_integers.fun
-- Or: fun examples/types_integers.fun

docs/examples/types_overview.md

@@ -1,9 +0,0 @@
-# types_overview.fun — overview
-
-What it shows
-- Overview of language types with small examples.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/types_overview.fun
-- Or: fun examples/types_overview.fun

docs/examples/uint_types.md

@@ -1,9 +0,0 @@
-# uint_types.fun — overview
-
-What it shows
-- Unsigned integer types and operations; ranges and conversions.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/uint_types.fun
-- Or: fun examples/uint_types.fun

docs/examples/unix_socket_echo.md

@@ -1,12 +0,0 @@
-# unix_socket_echo.fun — overview
-
-What it shows
-- Local domain (UNIX) socket echo server/client demonstration.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/unix_socket_echo.fun
-- Or: fun examples/unix_socket_echo.fun
-
-Notes
-- Uses a UNIX domain socket path on the local filesystem; ensure you have permissions to create it.

docs/examples/version.md

@@ -1,9 +0,0 @@
-# version.fun — overview
-
-What it shows
-- Prints VM and version info for the Fun interpreter/runtime.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/version.fun
-- Or: fun examples/version.fun

docs/examples/while_test.md

@@ -1,9 +0,0 @@
-# while_test.fun — overview
-
-What it shows
-- Simple while loop example; loop conditions and counters.
-
-How to run
-- export FUN_LIB_DIR="./lib"
-- ./build_debug/fun examples/while_test.fun
-- Or: fun examples/while_test.fun

docs/external/README.md

@@ -1,23 +0,0 @@
-# External integrations (optional extensions)
-
-This section documents Fun's optional, build-time selectable extensions. Each page covers:
-- How to enable the extension via CMake option (FUN_WITH_*)
-- Build requirements and detection notes
-- Available opcodes and/or helper functions
-- Minimal usage examples and links to example scripts
-
-## Extensions:
-
-- [cURL (libcurl)](./curl.md)
-- [INI (iniparser)](./ini.md)
-- [JSON (json-c)](./json.md)
-- [libxml2 (XML)](./xml2.md)
-- [SQLite](./sqlite.md)
-- [PCRE2 (Perl-compatible regex)](./pcre2.md)
-- [PC/SC (Smart cards)](./pcsc.md)
-- [OpenSSL](./openssl.md)
-
-## Notes:
-
-- These integrations are optional; the VM compiles without them.
-- When disabled, related builtins usually return empty strings/neutral values rather than fail hard, mirroring existing optionality patterns.

docs/faq.md

@@ -1,22 +0,0 @@
-# FAQ
-
-Answers to common questions.
-
-## I built Fun but includes aren't found
-Set `FUN_LIB_DIR` to the repository's `./lib` directory when running without installation:
-```
-FUN_LIB_DIR=./lib ./build/fun examples/hello.fun
-```
-See [includes.md](./includes.md).
-
-## How do I start the REPL?
-Run `fun -i` (or run `fun` without a script, depending on version). See [repl.md](./repl.md).
-
-## Which build target should I use?
-Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See [build.md](./build.md).
-
-## Where are the standard libraries?
-Under [`./lib/`](../lib/). See [stdlib.md](./stdlib.md) for an overview.
-
-## Where can I find internals and opcodes?
-Browse [src/vm](../src/vm/) and [internals.md](./internals.md) / [opcodes.md](./opcodes.md).

docs/roadmap.md

@@ -1,21 +0,0 @@
-# Roadmap
-
-This page outlines high-level areas of focus and points to places where you can help.
-
-## Themes
-- Developer experience: docs, examples, REPL polish
-- Optional extensions: stabilize and document supported integrations
-- Performance: steady improvements in hot paths and data structures
-- Safety: clearer error messages, diagnostics, and sandboxing guidance
-
-## Near-term
-- Expand CLI reference and examples ([cli.md](./cli.md))
-- Improve testing docs and coverage ([writing-tests.md](./writing-tests.md))
-- Fill gaps in stdlib documentation ([stdlib.md](./stdlib.md))
-
-## Medium-term
-- Bytecode/reference updates as internals evolve ([bytecode-format.md](./bytecode-format.md), [internals.md](./internals.md))
-- Embedding guides and host API stability ([embedding.md](./embedding.md), [rust.md](./rust.md))
-
-## Contributing
-See [contributing.md](./contributing.md) for how to propose and implement items. Track concrete tasks via repository issues and PRs.

web/_posts/2026-01-25-announcing-fun-0.37.62.md

@@ -148,8 +148,8 @@ If you're curious about Fun, check out:
 
 - [Website](https://fun-lang.xyz)
 - [Git Repository](https://git.xw3.org/fun/fun){:class="git"}
-- [Fun Handbook](https://git.xw3.org/fun/fun/src/branch/main/docs/handbook.md){:class="git"}
-- [Fun REPL Guide](https://git.xw3.org/fun/fun/src/branch/main/docs/repl.md){:class="git"}
+- [Fun Handbook](https://fun-lang.xyz/documentation/handbook/){:class="git"}
+- [Fun REPL Guide](https://fun-lang.xyz/documentation/repl/){:class="git"}
 - [Specification v0.3](https://git.xw3.org/fun/fun/src/branch/main/spec/v0.3.md){:class="git"}
 - [Examples](https://git.xw3.org/fun/fun/src/branch/main/examples){:class="git"}
 - [Standard Library](https://git.xw3.org/fun/fun/src/branch/main/lib){:class="git"}
@@ -159,9 +159,9 @@ The examples directory contains demonstrations of most Fun features, from basic
 
 ### For Developers
 
-- [Fun Internals](https://git.xw3.org/fun/fun/src/branch/main/docs/internals.md){:class="git"}
-- [Fun Opcodes](https://git.xw3.org/fun/fun/src/branch/main/docs/opcodes.md){:class="git"}
-- [Basic Rust Opcodes Support](https://git.xw3.org/fun/fun/src/branch/main/docs/rust.md){:class="git"}
+- [Fun Internals](https://fun-lang.xyz/documentation/internals/){:class="git"}
+- [Fun Opcodes](https://fun-lang.xyz/documentation/opcodes/){:class="git"}
+- [Basic Rust Opcodes Support](https://fun-lang.xyz/documentation/rust/){:class="git"}
 
 ### The Road Ahead
 

web/documentation/arrays.md

@@ -1,3 +1,29 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Arrays in Fun
+subtitle: Working with arrays, creation, indexing/slicing, iteration patterns, helpers, and idioms.
+description: Working with arrays, creation, indexing/slicing, iteration patterns, helpers, and idioms.
+permalink: /documentation/arrays/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Arrays in Fun
 
 This guide focuses on arrays: creation, indexing, mutation, iteration, slicing, and common gotchas. It complements the quick overview in types.md with a deeper, example‑driven treatment.

web/documentation/asyncio.md

@@ -1,3 +1,29 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Async I/O ("asyncio") in Fun
+subtitle: Async I/O primitives and patterns, non-blocking sockets, fd polling, examples, and best practices.
+description: Async I/O primitives and patterns, non-blocking sockets, fd polling, examples, and best practices.
+permalink: /documentation/asyncio/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Async I/O ("asyncio") in Fun
 
 This guide explains the new asynchronous I/O primitives in Fun and how to use them to build non-blocking network and file descriptor workflows. It covers the core concepts, available helpers, common patterns, and runnable examples from the repository.
@@ -197,14 +223,14 @@ Q: Is there an async/await syntax?
 A: Not at this time. The model is explicit non-blocking I/O with polling helpers. You can build lightweight schedulers on top if desired.
 
 Q: Does this work on all platforms?
-A: The helpers map to portable OS facilities exposed by the VM. Details may vary by platform; see docs/troubleshooting.md and open an issue if you hit differences.
+A: The helpers map to portable OS facilities exposed by the VM. Details may vary by platform; see documentation/troubleshooting.md and open an issue if you hit differences.
 
 Q: How do I integrate with the REPL?
 A: You can prototype small non-blocking fragments in the REPL, but full networking examples are easier to run as scripts.
 
 ## See also
 
-- [examples.md](./examples.md) — Running bundled examples
-- [includes.md](./includes.md) — Include paths and library discovery
-- [opcodes.md](./opcodes.md) — VM opcodes overview
-- [troubleshooting.md](./troubleshooting.md) — Common issues and quick fixes
+- [examples.md](./examples/) — Running bundled examples
+- [includes.md](./includes/) — Include paths and library discovery
+- [opcodes.md](./opcodes/) — VM opcodes overview
+- [troubleshooting.md](./troubleshooting/) — Common issues and quick fixes

web/documentation/build.md

@@ -1,3 +1,29 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Building Fun
+subtitle: How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST, FUN_WITH_OPENSSL).
+description: How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST, FUN_WITH_OPENSSL).
+permalink: /documentation/build/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Building Fun
 
 This guide describes how to build Fun from source using CMake and the available build options.
@@ -83,7 +109,7 @@ If `FUN_WITH_OPENSSL` is enabled, CMake must detect your system OpenSSL (libcryp
 
 ## Running
 - CLI: run the `fun` executable from your build directory.
-- REPL: `fun -i` or just run `fun` without a script, depending on your CLI version (see [cli.md](./cli.md)).
-- Examples: see [examples.md](./examples.md).
+- REPL: `fun -i` or just run `fun` without a script, depending on your CLI version (see [cli.md](./cli/)).
+- Examples: see [examples.md](./examples/).
 
 Tip: When running from the repository without installation, set `FUN_LIB_DIR` to the local `./lib` so includes can find the stdlib.

web/documentation/bytecode-format.md

@@ -1,6 +1,32 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Bytecode Format (Overview)
+subtitle: Reference for the bytecode format (split out from internals for convenience).
+description: Reference for the bytecode format (split out from internals for convenience).
+permalink: /documentation/bytecode-format/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Bytecode Format (Overview)
 
-This document summarizes the Fun bytecode format. For deep VM details, see [internals.md](./internals.md).
+This document summarizes the Fun bytecode format. For deep VM details, see [internals.md](./internals/).
 
 ## Goals
 - Compact representation for fast loading and dispatch

web/documentation/cli.md

@@ -1,15 +1,41 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Fun CLI
+subtitle: Command-line usage of the `fun` executable, synopsis, options, exit codes, includes and library paths.
+description: Command-line usage of the `fun` executable, synopsis, options, exit codes, includes and library paths.
+permalink: /documentation/cli/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Fun CLI
 
 Reference for the `fun` command-line interface.
 
-For a complete usage guide (including REPL details, environment variables, include paths, examples, and install locations), see [fun.md](./fun.md).
+For a complete usage guide (including REPL details, environment variables, include paths, examples, and install locations), see [fun.md](./fun/).
 
 ## Synopsis
 ```
 fun [options] <script.fun> [-- args...]
 ```
 
-If no script is supplied and interactive mode is available, `fun` starts a REPL (see [repl.md](./repl.md)).
+If no script is supplied and interactive mode is available, `fun` starts a REPL (see [repl.md](./repl/)).
 
 ## Common options
 - `-i`, `--repl` - start an interactive REPL
@@ -26,7 +52,7 @@ Options may vary between versions; run `fun --help` to see what your build suppo
 - `FUN_LIB_DIR` - environment variable that points to the stdlib location; when running from the repo, set this to `./lib`.
 - `DEFAULT_LIB_DIR` - compiled-in fallback path determined at build/install time.
 
-See also: [includes.md](./includes.md) for namespaced includes and search order.
+See also: [includes.md](./includes/) for namespaced includes and search order.
 
 ## Examples
 Run a script:

web/documentation/contributing.md

@@ -1,27 +1,53 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Contributing to Fun
+subtitle: How to contribute, project structure, coding style, running tests, and PR guidelines.
+description: How to contribute, project structure, coding style, running tests, and PR guidelines.
+permalink: /documentation/contributing/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Contributing to Fun
 
 Thanks for your interest in contributing! This guide covers the basics to get you productive quickly.
 
 ## Getting started
-- Clone the repo and build (see [build.md](./build.md)).
-- Run tests locally (see [testing.md](./testing.md)).
-- Explore examples (see [examples.md](./examples.md)).
+- Clone the repo and build (see [build.md](./build/)).
+- Run tests locally (see [testing.md](./testing/)).
+- Explore examples (see [examples.md](./examples/)).
 
 ## Project structure
 - `src/` - C core, VM, and opcode implementations ([src/vm](../src/vm/)).
 - `lib/` - Standard library written in Fun.
 - `examples/` - Example programs and showcases.
-- `docs/` - Documentation.
+- `documentation/` - Documentation.
 - `spec/` - Language specification drafts.
 
 ## Code style
 - C: C99, two-space indent, no tabs. Keep functions short and focused.
 - Fun: two-space indent, snake_case for functions, PascalCase for classes/constructors.
-- Prefer clear names over abbreviations. See [style-guide.md](./style-guide.md).
+- Prefer clear names over abbreviations. See [style-guide.md](./style-guide/).
 
 ## Development workflow
 1. Create a small, focused branch.
-2. Add/adjust tests for behavior changes (see [writing-tests.md](./writing-tests.md)).
+2. Add/adjust tests for behavior changes (see [writing-tests.md](./writing-tests/)).
 3. Update docs if user-visible behavior changes.
 4. Submit a PR with a clear description and rationale.
 
@@ -37,4 +63,4 @@ Please include:
 - `fun --version` output
 
 ## Code of Conduct
-Be respectful and inclusive. See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) in the repository root.
+Be respectful and inclusive. See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT/) in the repository root.

web/documentation/documentation.md

@@ -4,9 +4,9 @@ published: true
 noToc: true
 noComments: false
 noDate: false
-title: Documentation
-subtitle: Some documentation about the Fun programming language.
-description: The Fun Documentation
+title: Fun - Documentation
+subtitle: Detailed documentation for the Fun programming language.
+description: The Fun Documentation Index
 permalink: /documentation/
 lang: en
 tags:
@@ -24,26 +24,71 @@ tags:
 - repl
 ---
 
+# Fun Documentation Index
+
+This file serves as an index of the documents in this directory. Links are relative and can be opened directly on Git hosting or locally.
+
 ## Basics
 
-[The Fun Handbook is found here](https://git.xw3.org/fun/fun/src/branch/main/docs/handbook.md){:class="git"}!
-
-Look at [https://git.xw3.org/fun/fun/src/branch/main/docs](https://git.xw3.org/fun/fun/src/branch/main/docs){:class="git"} for more detailed documentation!
-
-## More information
-
+- [handbook.md](./handbook.md) - Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview.
+- [Fun REPL Guide](./repl.md) - REPL guide: how to build/launch, editing and history, completions, REPL-on-error, and tips.
 - [Specification v0.3](https://git.xw3.org/fun/fun/src/branch/main/spec/v0.3.md){:class="git"}
 - [Specification v0.2](https://git.xw3.org/fun/fun/src/branch/main/spec/v0.2.md){:class="git"}
 - [Specification v0.1](https://git.xw3.org/fun/fun/src/branch/main/spec/v0.1.md){:class="git"}
 - [Examples](https://git.xw3.org/fun/fun/src/branch/main/examples){:class="git"}
 - [Standard Library](https://git.xw3.org/fun/fun/src/branch/main/lib){:class="git"}
-- [Fun REPL Guide](https://git.xw3.org/fun/fun/src/branch/main/docs/repl.md){:class="git"}
 
 The examples directory contains demonstrations of most Fun features, from basic "Hello, World!" to threading, networking, classes, and more. The lib directory includes modules written in Fun itself.
 
-## For Developers
+## Overview
 
-- [Fun Internals](https://git.xw3.org/fun/fun/src/branch/main/docs/internals.md){:class="git"}
-- [Fun Opcodes](https://git.xw3.org/fun/fun/src/branch/main/docs/opcodes.md){:class="git"}
-- [Basic Rust Opcodes Support](https://git.xw3.org/fun/fun/src/branch/main/docs/rust.md){:class="git"}
+- [types.md](./types.md) - Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes.
+- [numbers.md](./numbers.md) - Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns.
+- [strings.md](./strings.md) - Working with strings: literals/escaping, concatenation, substr/find, split, and conversions.
+- [arrays.md](./arrays.md) - Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms.
+- [maps.md](./maps.md) - Working with maps: construction, lookup/update, merging, iteration, and common patterns.
+- [includes.md](./includes.md) - Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with `as`.
+- [opcodes.md](./opcodes.md) - VM opcodes overview grouped by domain with brief behavior/stack notes.
+- [internals.md](./internals.md) - Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch.
+- [rust.md](./rust.md) - Writing Rust-backed opcodes and wiring them into the C VM; build/setup notes.
+- [examples.md](./examples.md) - How to run the examples and the interactive showcase script, with environment tips.
+- [testing.md](./testing.md) - How to build and run tests/targets with CMake/CTest, and where to add new tests.
+- [troubleshooting.md](./troubleshooting.md) - Common issues and quick fixes for build, includes, and REPL usage.
 
+## New and supplemental guides
+
+- [build.md](./build.md) - How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST, FUN_WITH_OPENSSL).
+- [cli.md](./cli.md) - Command-line usage of the `fun` executable: synopsis, options, exit codes, includes and library paths.
+- [fun.md](./fun.md) - Full usage guide for the `fun` executable: invocation patterns, REPL, env vars, include paths, examples, and install locations.
+- [asyncio.md](./asyncio.md) - Async I/O primitives and patterns: non-blocking sockets, fd polling, examples, and best practices.
+- [funstx.md](./funstx.md) - Syntax checker for .fun files with optional --fix auto-corrections; usage, exit codes, and limitations.
+- [contributing.md](./contributing.md) - How to contribute: project structure, coding style, running tests, and PR guidelines.
+- [style-guide.md](./style-guide.md) - Coding conventions for C and Fun (indentation, naming, idioms).
+- [stdlib.md](./stdlib.md) - Overview of the standard library modules under ./lib with one-line summaries.
+- [embedding.md](./embedding.md) - Embedding the VM from C/Rust, lifecycle, and host integration tips.
+- [errors-and-diagnostics.md](./errors-and-diagnostics.md) - Understanding parser/runtime errors and enabling diagnostics.
+- [performance.md](./performance.md) - Build/runtime tuning tips and patterns for better performance.
+- [security-and-sandboxing.md](./security-and-sandboxing.md) - Trust boundaries, I/O expectations, and capability restrictions.
+- [faq.md](./faq.md) - Frequently asked questions and quick answers.
+- [website.md](./website.md) - Documentation for the [fun-lang.xyz](https://fun-lang.xyz) website in the `./web/` directory.
+- [writing-tests.md](./writing-tests.md) - How to author new tests for Fun and opcode components.
+- [bytecode-format.md](./bytecode-format.md) - Reference for the bytecode format (split out from internals for convenience).
+- [roadmap.md](./roadmap.md) - High-level direction, planned features, and pointers to issues.
+
+## Examples
+
+ - [examples/README.md](./examples/README.md) - Catalog of all example scripts under ./examples/: what each area contains, how to run them, required env vars, and extension requirements.
+
+## External extensions
+
+Documentation for optional, build-time selectable integrations lives in [external/](./external/):
+
+- [Index of extensions](./external/README.md)
+ - Highlights: [cURL](./external/curl.md), [INI](./external/ini.md), [JSON](./external/json.md), [XML (libxml2)](./external/xml2.md), [SQLite](./external/sqlite.md), [PCRE2](./external/pcre2.md), [PC/SC](./external/pcsc.md), [OpenSSL](./external/openssl.md)
+
+## Tips
+
+- When building from the repo without installing, set `FUN_LIB_DIR` to the local `./lib` directory so examples and the REPL can locate the stdlib.
+- For a broader project overview and quickstart, see the repository root [README.md](../../README.md).
+- Crypto examples:
+  - If built with `-DFUN_WITH_OPENSSL=ON`, try `examples/crypto/openssl_md5.fun`.

web/documentation/embedding.md

@@ -1,10 +1,36 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Embedding Fun
+subtitle: Embedding the VM from C/Rust, lifecycle, and host integration tips.
+description: Embedding the VM from C/Rust, lifecycle, and host integration tips.
+permalink: /documentation/embedding/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Embedding Fun
 
 This guide outlines how to embed the Fun VM in a host application and extend it from C/Rust.
 
 ## Overview
 - The VM is implemented in C (see [src/vm](../src/vm/)).
-- Optional Rust-based opcodes can be enabled via `FUN_WITH_RUST` (see [rust.md](./rust.md)).
+- Optional Rust-based opcodes can be enabled via `FUN_WITH_RUST` (see [rust.md](./rust/)).
 
 ## Embedding from C
 While the exact API surface may evolve, a typical embedding flow looks like:
@@ -26,4 +52,4 @@ When `FUN_WITH_RUST=ON`, a Rust static library from [`src/rust/`](../src/rust/)
 - Implement new opcodes/functions in Rust.
 - Expose a C ABI for the VM to call into.
 
-See [rust.md](./rust.md) for details and example code.
+See [rust.md](./rust/) for details and example code.

web/documentation/errors-and-diagnostics.md

@@ -1,3 +1,29 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Errors and Diagnostics
+subtitle: Understanding parser/runtime errors and enabling diagnostics.
+description: Understanding parser/runtime errors and enabling diagnostics.
+permalink: /documentation/errors-and-diagnostics/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Errors and Diagnostics
 
 This guide helps you understand common error messages and how to collect useful diagnostics.
@@ -8,7 +34,7 @@ This guide helps you understand common error messages and how to collect useful
 - Runtime errors: type mismatches, out-of-range access, invalid operations.
 
 ## Enabling diagnostics
-- Build with `-DFUN_DEBUG=ON` to enable additional assertions and debug messages (see [build.md](./build.md)).
+- Build with `-DFUN_DEBUG=ON` to enable additional assertions and debug messages (see [build.md](./build/)).
 - Run with smaller, focused scripts to isolate issues.
 
 ## Getting useful reports

web/documentation/examples.md

@@ -1,3 +1,29 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - Running the Examples
+subtitle: How to run the examples and the interactive showcase script, with environment tips.
+description: How to run the examples and the interactive showcase script, with environment tips.
+permalink: /documentation/examples/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
 # Running the Examples
 
 This page shows how to run the example programs included with the repository and how to use the interactive showcase script.