From 6e6a5fed009b6cc4e7bdf178dbb0597b5188a857 Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Mon, 9 Jun 2025 13:14:03 +0200
Subject: [PATCH 1/3] improve and simplify getting started page

---
 README.md                                |   2 +-
 content/_index.md                        | 232 ++++++++++++++++++-----
 content/documentation/getting-started.md | 133 ++++++-------
 3 files changed, 244 insertions(+), 123 deletions(-)

diff --git a/README.md b/README.md
index b086625..1b25fb7 100644
--- a/README.md
+++ b/README.md
@@ -31,4 +31,4 @@ zola serve # build & serve
 
 ```bash
 zola build # build & publish
-```
\ No newline at end of file
+```
diff --git a/content/_index.md b/content/_index.md
index 5d2f908..cefab14 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -1,84 +1,218 @@
 +++
-title = "Phel: A Functional Lisp Dialect for PHP Developers"
+title = "Getting Started & Developer Experience"
+weight = 1
 +++
 
-**Phel** is a functional programming language that compiles down to PHP. It's a modern Lisp dialect inspired by [Clojure](https://clojure.org/) and [Janet](https://janet-lang.org/), tailored to bring functional elegance and expressive code to the world of PHP development.
+## Requirements
 
-<p align="center">
-    <img src="/images/logo_phel.svg" width="350" alt="Phel language logo"/>
-</p>
+Phel requires PHP 8.2 or higher and [Composer](https://getcomposer.org/).
 
-## Join the Phel Developer Community
+---
 
-Got questions? Want to chat about macros, tail recursion, or why parentheses are awesome?  
-Swing by the [Phel Gitter channel](https://gitter.im/phel-lang/community)—we're friendly, nerdy, and always happy to talk code.
+## Quick Start with a Scaffolding Template
 
-## Key Features of Phel
+You can create a new Phel commandline project via Composer’s `create-project` command:
 
-Why code in Phel? Here's what makes it click:
+```bash
+composer create-project --stability dev phel-lang/cli-skeleton example-app
+cd example-app
+composer repl
+```
+
+> Alternatively, use [phel-lang/web-skeleton](https://github.com/phel-lang/web-skeleton) for a web project. More details in the [README](https://packagist.org/packages/phel-lang/cli-skeleton).
+
+---
+
+## Manual Setup with Composer
+
+1. Initialize a new project:
+
+```bash
+mkdir hello-world
+cd hello-world
+composer init
+```
+
+2. Require Phel:
+
+```bash
+composer require phel-lang/phel-lang
+```
+
+> Optionally create `phel-config.php`:
+> ```php
+> <?php
+> return (new \Phel\Config\PhelConfig())->setSrcDirs(['src']);
+> ```
+> See all [configuration options](/documentation/configuration).
+
+3. Create the source directory and a file:
+
+```bash
+mkdir src
+```
+
+4. Write your first Phel program:
+
+```phel
+;; src/main.phel
+(ns hello-world\main)
+(println "Hello, World!")
+```
+
+---
+
+## Running the Code
+
+### From the Command Line
+
+```bash
+vendor/bin/phel run src/main.phel
+# or
+vendor/bin/phel run hello-world\\main
+# or
+vendor/bin/phel run "hello-world\main"
+```
+
+Output:
+
+```
+Hello, World!
+```
+
+### With a PHP Server
+
+```php
+// src/index.php
+<?php
+
+use Phel\Phel;
+
+$projectRootDir = __DIR__ . '/../';
+
+require $projectRootDir . 'vendor/autoload.php';
+
+Phel::run($projectRootDir, 'hello-world\\main');
+```
+
+Start the server:
+
+```bash
+php -S localhost:8000 ./src/index.php
+```
 
-- ✅ Runs on the rock-solid PHP ecosystem
-- 🧠 Helpful and human-readable error messages
-- 📚 Built-in persistent data structures: Lists, Vectors, Maps, Sets
-- 🧩 Macro system for advanced metaprogramming
-- 🔁 Tail-recursive function support
-- ✨ Minimal, readable Lisp syntax
-- 💬 Interactive REPL for tinkering and prototyping
+Visit [http://localhost:8000](http://localhost:8000) to see the output.
 
-## Why Choose Phel for Functional Programming in PHP?
+> Consider using `phel build` for performance. See [Build the project](/documentation/cli-commands/#build-the-project).
 
-Phel started as an [experiment in writing functional PHP](/blog/functional-programming-in-php) and quickly turned into its own thing.
+---
 
-It exists because we wanted:
+## Launch the REPL
 
-- A Lisp-inspired functional language
-- That runs on affordable PHP hosting
-- That's expressive, debug-friendly, and easy to pick up
+Start an interactive REPL in any project with Phel installed:
 
-If you've ever wished PHP was a bit more... functional, Phel is for you.
+```bash
+./vendor/bin/phel repl
+```
 
-## See Phel in Action — Sample Code
+You can evaluate Phel expressions:
 
 ```phel
-# Define a namespace
-(ns my\example)
+phel:1> (def name "World")
+phel:2> (println "Hello" name)
+Hello World
+```
+
+The REPL understands multi-line expressions and supports `doc`, `require` and `use` helpers.
+
+> More in the [REPL documentation](/documentation/repl).
+
+---
+
+## Debugging Helpers
+
+Use PHP debugging tools:
+
+```phel
+(def result (+ 40 2))
+(php/dump result)
+```
+
+Enable temporary PHP files for inspection:
+
+```php
+// phel-config-local.php
+return (require __DIR__ . '/phel-config.php')
+    ->setKeepGeneratedTempFiles(true);
+```
 
-# Create a variable
-(def my-name "world")
+> Learn more on the [Debug page](/documentation/debug).
 
-# Define a function
-(defn print-name [your-name]
-  (print "hello" your-name))
+---
 
-# Call the function
-(print-name my-name)
+## Building and Deploying
+
+Run directly:
+
+```bash
+vendor/bin/phel run src/main.phel
+```
+
+Build for production:
+
+```bash
+php phel build
+php out/index.php
 ```
 
-If you know Lisp or Clojure, you'll feel right at home. If you don't—this is a great place to start.
+> More in the [CLI commands](/documentation/cli-commands/#run-a-script).
+
+---
 
-## Try Phel Instantly with Docker
+## Testing
 
-No setup? No problem. You can run Phel's REPL right away:
+Run Phel tests:
 
 ```bash
-docker run -it --rm phellang/repl
+vendor/bin/phel test --filter foo
 ```
 
-![Try Phel animation](/try-phel.gif "Try Phel Animation")
+Run PHP-based tests:
+
+```bash
+composer test
+```
+
+> More in the [Testing section](/documentation/testing).
+
+---
+
+## Handy Macros
+
+Example:
+
+```phel
+(when condition
+  (println "only printed when condition is true"))
+
+(-> {:name "Phel"}
+    (:name)
+    (str "Lang"))
+```
 
-## Get Started with Phel in Minutes
+These macros keep code concise and readable. Explore the rest of the library for more utilities.
 
-All you need is [PHP >=8.2](https://www.php.net/) and [Composer](https://getcomposer.org/). 
+> See the [Macros page](/documentation/macros) for more.
 
-> Follow our [Getting Started Guide](/documentation/getting-started) to build and run your first Phel program today.
+---
 
-## Development Status & How to Contribute
+## Editor Support
 
-Phel is approaching its 1.0 release, but we're still actively refining the language —and yes, breaking changes may happen.
+Phel supports:
 
-We're building this in the open. That means:
-- Found a bug? File an issue.
-- Got a cool idea? Open a pull request.
-- Want to shape the language's future? Let's talk.
+- [VSCode extension](https://github.com/phel-lang/phel-vs-code-extension)
+- [PhpStorm syntax plugin](https://github.com/phel-lang/phel-phpstorm-syntax)
+- [Emacs interactive mode](https://codeberg.org/mmontone/interactive-lang-tools/src/branch/master/backends/phel)
+- [Vim plugin (in progress)](https://github.com/danirod/phel.vim)
 
-Your feedback, ideas, and code help Phel grow into something great.
+> Details also in the [Editor Support](/documentation/getting-started/#editor-support) section.
diff --git a/content/documentation/getting-started.md b/content/documentation/getting-started.md
index 35cf978..8445d5b 100644
--- a/content/documentation/getting-started.md
+++ b/content/documentation/getting-started.md
@@ -1,132 +1,119 @@
 +++
-title = "Getting started"
+title = "Getting Started"
 weight = 1
 +++
 
 ## Requirements
 
-Phel requires PHP 8.2 or higher and [Composer](https://getcomposer.org/).
+- PHP 8.2+
+- [Composer](https://getcomposer.org/)
 
-## Quick start with a scaffolding template
+## Quick Start
 
-To get started right away, you can create a new Phel commandline project via Composer's `create-project` command:
+Scaffold a new project:
 
 ```bash
 composer create-project --stability dev phel-lang/cli-skeleton example-app
-```
-
-Once the project has been created, start the REPL (read-evaluate-print loop) to try Phel.
-
-```bash
 cd example-app
 composer repl
 ```
 
-> Alternatively to the [phel-lang/cli-skeleton](https://github.com/phel-lang/cli-skeleton), you can also use [phel-lang/web-skeleton](https://github.com/phel-lang/web-skeleton) for a web project. More information can be found in the [README](https://packagist.org/packages/phel-lang/cli-skeleton) of the project.
-
+> For web projects: [web-skeleton](https://github.com/phel-lang/web-skeleton)
 
-## Manually initialize a new project using Composer
-
-The easiest way to get started is by setting up a new Composer project. First, create a new directory and initialize a new Composer project.
+## Manual Setup
 
 ```bash
-mkdir hello-world
-cd hello-world
+mkdir hello-world && cd hello-world
 composer init
-```
-
-Next, require Phel as a dependency.
-
-```bash
 composer require phel-lang/phel-lang
+mkdir src
 ```
 
-> Optionally, you can create `phel-config.php` at the root of the project:
-> ```php
-> <?php
-> 
-> return (new \Phel\Config\PhelConfig())
->     ->setSrcDirs(['src']);
-> ```
-> Read the docs to see all available [configuration](/documentation/configuration) options for Phel.
-
-Then, create a new directory `src` with a file `main.phel` inside this directory.
+Optional config (`phel-config.php`):
 
-```bash
-mkdir src
+```php
+<?php
+return (new \Phel\Config\PhelConfig())
+  ->setSrcDirs(['src']);
 ```
 
-The file `main.phel` contains the actual code of the project. It defines the namespace and prints "Hello, World!".
+Sample Phel file (`src/main.phel`):
 
 ```phel
-# inside `src/main.phel`
 (ns hello-world\main)
-
 (println "Hello, World!")
 ```
 
-## Running the code
-
-There are two ways to run the code: from the command line and with a PHP Server.
+## Run Code
 
-### From the Command line
-
-Code can be executed from the command line by calling the `vendor/bin/phel run` command, followed by the file path or namespace:
+**From CLI:**
 
 ```bash
 vendor/bin/phel run src/main.phel
-# or
-vendor/bin/phel run hello-world\\main
-# or
-vendor/bin/phel run "hello-world\main"
 ```
 
-The output will be:
+**With PHP Server:**
 
+```php
+<?php
+require __DIR__ . '/../vendor/autoload.php';
+\Phel\Phel::run(__DIR__ . '/../', 'hello-world\\main');
 ```
-Hello, World!
+
+```bash
+php -S localhost:8000 ./src/index.php
 ```
 
-### With a PHP Server
+## REPL
 
-> Check the [web-skeleton project on GitHub](https://github.com/phel-lang/web-skeleton).
+```bash
+vendor/bin/phel repl
+```
 
-The file `index.php` will be executed by the PHP Server. It initializes the Phel Runtime and loads the namespace from the `main.phel` file described above, to start the application.
+Try:
 
-```php
-// src/index.php
-<?php
+```phel
+(def name "World")
+(println "Hello" name)
+```
 
-use Phel\Phel;
+## Debugging
 
-$projectRootDir = __DIR__ . '/../';
+```phel
+(php/dump (+ 40 2))
+```
 
-require $projectRootDir . 'vendor/autoload.php';
+Enable temp files in `phel-config-local.php`:
 
-Phel::run($projectRootDir, 'hello-world\\main');
+```php
+<?php
+return (require __DIR__ . '/phel-config.php')
+  ->setKeepGeneratedTempFiles(true);
 ```
 
-The PHP Server can now be started.
+## Build & Deploy
 
 ```bash
-# Start server
-php -S localhost:8000 ./src/index.php
+vendor/bin/phel build
+php out/index.php
 ```
 
-In the browser, the URL `http://localhost:8000` will now print "Hello, World!".
+## Testing
 
-> When using a web server, consider building the project to avoid compilation time for each request; so PHP will run the transpiled PHP code instead to gain performance. See more [Buid the project](/documentation/cli-commands/#build-the-project).
-
-## Launch the REPL
+```bash
+vendor/bin/phel test --filter foo
+```
 
-To try Phel you can run a REPL by executing the `./vendor/bin/phel repl` command.
+## Handy Macros
 
-> Read more about the [REPL](/documentation/repl) in its own chapter.
+```phel
+(when condition (println "if true"))
+(-> {:name "Phel"} (:name) (str "Lang"))
+```
 
-## Editor support
+## Editor Support
 
-Phel comes with basic support for <a href="https://github.com/phel-lang/phel-vs-code-extension" target="_blank">
-VSCode</a>, <a href="https://github.com/phel-lang/phel-phpstorm-syntax" target="_blank">PhpStorm</a>, a
-<a href="https://codeberg.org/mmontone/interactive-lang-tools/src/branch/master/backends/phel" target="_blank">
-Emacs mode with interactive capabilities</a> and a <a href="https://github.com/danirod/phel.vim" target="_blank">Vim
-plugin</a> in the making.
+- [VSCode](https://github.com/phel-lang/phel-vs-code-extension)
+- [PhpStorm](https://github.com/phel-lang/phel-phpstorm-syntax)
+- [Emacs](https://codeberg.org/mmontone/interactive-lang-tools)
+- [Vim](https://github.com/danirod/phel.vim)

From 38e0d6ee6c9348eb72ec068ea0ed1559144c2f3f Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Mon, 9 Jun 2025 13:17:52 +0200
Subject: [PATCH 2/3] add links for more docs on getting started

---
 content/documentation/getting-started.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/content/documentation/getting-started.md b/content/documentation/getting-started.md
index 8445d5b..7a64dff 100644
--- a/content/documentation/getting-started.md
+++ b/content/documentation/getting-started.md
@@ -18,7 +18,7 @@ cd example-app
 composer repl
 ```
 
-> For web projects: [web-skeleton](https://github.com/phel-lang/web-skeleton)
+> For web projects: [web-skeleton](https://github.com/phel-lang/web-skeleton)  
 
 ## Manual Setup
 
@@ -64,6 +64,8 @@ require __DIR__ . '/../vendor/autoload.php';
 php -S localhost:8000 ./src/index.php
 ```
 
+> 📘 [More on running code](/documentation/cli-commands#run-a-script)
+
 ## REPL
 
 ```bash
@@ -77,6 +79,8 @@ Try:
 (println "Hello" name)
 ```
 
+> 📘 [More on REPL](/documentation/repl)
+
 ## Debugging
 
 ```phel
@@ -91,6 +95,8 @@ return (require __DIR__ . '/phel-config.php')
   ->setKeepGeneratedTempFiles(true);
 ```
 
+> 📘 [More on debugging](/documentation/debug)
+
 ## Build & Deploy
 
 ```bash
@@ -98,12 +104,16 @@ vendor/bin/phel build
 php out/index.php
 ```
 
+> 📘 [More on build](/documentation/cli-commands/#build-the-project)
+
 ## Testing
 
 ```bash
 vendor/bin/phel test --filter foo
 ```
 
+> 📘 [More on testing](/documentation/testing)
+
 ## Handy Macros
 
 ```phel
@@ -111,6 +121,8 @@ vendor/bin/phel test --filter foo
 (-> {:name "Phel"} (:name) (str "Lang"))
 ```
 
+> 📘 [More on macros](/documentation/macros)
+
 ## Editor Support
 
 - [VSCode](https://github.com/phel-lang/phel-vs-code-extension)

From feb059804ccb1cd103550f97b3a5c671c0601efb Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Mon, 9 Jun 2025 13:20:46 +0200
Subject: [PATCH 3/3] rollback homepage as it was before

changed by mistake
---
 content/_index.md | 232 ++++++++++------------------------------------
 1 file changed, 49 insertions(+), 183 deletions(-)

diff --git a/content/_index.md b/content/_index.md
index cefab14..61314b6 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -1,218 +1,84 @@
 +++
-title = "Getting Started & Developer Experience"
-weight = 1
+title = "Phel: A Functional Lisp Dialect for PHP Developers"
 +++
 
-## Requirements
+**Phel** is a functional programming language that compiles down to PHP. It's a modern Lisp dialect inspired by [Clojure](https://clojure.org/) and [Janet](https://janet-lang.org/), tailored to bring functional elegance and expressive code to the world of PHP development.
 
-Phel requires PHP 8.2 or higher and [Composer](https://getcomposer.org/).
+<p align="center">
+    <img src="/images/logo_phel.svg" width="350" alt="Phel language logo"/>
+</p>
 
----
+## Join the Phel Developer Community
 
-## Quick Start with a Scaffolding Template
+Got questions? Want to chat about macros, tail recursion, or why parentheses are awesome?  
+Swing by the [Phel Gitter channel](https://gitter.im/phel-lang/community)—we're friendly, nerdy, and always happy to talk code.
 
-You can create a new Phel commandline project via Composer’s `create-project` command:
+## Key Features of Phel
 
-```bash
-composer create-project --stability dev phel-lang/cli-skeleton example-app
-cd example-app
-composer repl
-```
-
-> Alternatively, use [phel-lang/web-skeleton](https://github.com/phel-lang/web-skeleton) for a web project. More details in the [README](https://packagist.org/packages/phel-lang/cli-skeleton).
-
----
-
-## Manual Setup with Composer
-
-1. Initialize a new project:
-
-```bash
-mkdir hello-world
-cd hello-world
-composer init
-```
-
-2. Require Phel:
-
-```bash
-composer require phel-lang/phel-lang
-```
-
-> Optionally create `phel-config.php`:
-> ```php
-> <?php
-> return (new \Phel\Config\PhelConfig())->setSrcDirs(['src']);
-> ```
-> See all [configuration options](/documentation/configuration).
-
-3. Create the source directory and a file:
-
-```bash
-mkdir src
-```
-
-4. Write your first Phel program:
-
-```phel
-;; src/main.phel
-(ns hello-world\main)
-(println "Hello, World!")
-```
-
----
-
-## Running the Code
-
-### From the Command Line
-
-```bash
-vendor/bin/phel run src/main.phel
-# or
-vendor/bin/phel run hello-world\\main
-# or
-vendor/bin/phel run "hello-world\main"
-```
-
-Output:
-
-```
-Hello, World!
-```
-
-### With a PHP Server
-
-```php
-// src/index.php
-<?php
-
-use Phel\Phel;
-
-$projectRootDir = __DIR__ . '/../';
-
-require $projectRootDir . 'vendor/autoload.php';
-
-Phel::run($projectRootDir, 'hello-world\\main');
-```
-
-Start the server:
-
-```bash
-php -S localhost:8000 ./src/index.php
-```
+Why code in Phel? Here's what makes it click:
 
-Visit [http://localhost:8000](http://localhost:8000) to see the output.
+- ✅ Runs on the rock-solid PHP ecosystem
+- 🧠 Helpful and human-readable error messages
+- 📚 Built-in persistent data structures: Lists, Vectors, Maps, Sets
+- 🧩 Macro system for advanced metaprogramming
+- 🔁 Tail-recursive function support
+- ✨ Minimal, readable Lisp syntax
+- 💬 Interactive REPL for tinkering and prototyping
 
-> Consider using `phel build` for performance. See [Build the project](/documentation/cli-commands/#build-the-project).
+## Why Choose Phel for Functional Programming in PHP?
 
----
+Phel started as an [experiment in writing functional PHP](/blog/functional-programming-in-php) and quickly turned into its own thing.
 
-## Launch the REPL
+It exists because we wanted:
 
-Start an interactive REPL in any project with Phel installed:
+- A Lisp-inspired functional language
+- That runs on affordable PHP hosting
+- That's expressive, debug-friendly, and easy to pick up
 
-```bash
-./vendor/bin/phel repl
-```
+If you've ever wished PHP was a bit more... functional, Phel is for you.
 
-You can evaluate Phel expressions:
+## See Phel in Action — Sample Code
 
 ```phel
-phel:1> (def name "World")
-phel:2> (println "Hello" name)
-Hello World
-```
-
-The REPL understands multi-line expressions and supports `doc`, `require` and `use` helpers.
-
-> More in the [REPL documentation](/documentation/repl).
-
----
-
-## Debugging Helpers
-
-Use PHP debugging tools:
-
-```phel
-(def result (+ 40 2))
-(php/dump result)
-```
-
-Enable temporary PHP files for inspection:
-
-```php
-// phel-config-local.php
-return (require __DIR__ . '/phel-config.php')
-    ->setKeepGeneratedTempFiles(true);
-```
+# Define a namespace
+(ns my\example)
 
-> Learn more on the [Debug page](/documentation/debug).
+# Create a variable
+(def my-name "world")
 
----
+# Define a function
+(defn print-name [your-name]
+  (print "hello" your-name))
 
-## Building and Deploying
-
-Run directly:
-
-```bash
-vendor/bin/phel run src/main.phel
-```
-
-Build for production:
-
-```bash
-php phel build
-php out/index.php
+# Call the function
+(print-name my-name)
 ```
 
-> More in the [CLI commands](/documentation/cli-commands/#run-a-script).
-
----
+If you know Lisp or Clojure, you'll feel right at home. If you don't—this is a great place to start.
 
-## Testing
+## Try Phel Instantly with Docker
 
-Run Phel tests:
+No setup? No problem. You can run Phel's REPL right away:
 
 ```bash
-vendor/bin/phel test --filter foo
+docker run -it --rm phellang/repl
 ```
 
-Run PHP-based tests:
-
-```bash
-composer test
-```
-
-> More in the [Testing section](/documentation/testing).
-
----
-
-## Handy Macros
-
-Example:
-
-```phel
-(when condition
-  (println "only printed when condition is true"))
-
-(-> {:name "Phel"}
-    (:name)
-    (str "Lang"))
-```
+![Try Phel animation](/try-phel.gif "Try Phel Animation")
 
-These macros keep code concise and readable. Explore the rest of the library for more utilities.
+## Get Started with Phel in Minutes
 
-> See the [Macros page](/documentation/macros) for more.
+All you need is [PHP >=8.2](https://www.php.net/) and [Composer](https://getcomposer.org/).
 
----
+> Follow our [Getting Started Guide](/documentation/getting-started) to build and run your first Phel program today.
 
-## Editor Support
+## Development Status & How to Contribute
 
-Phel supports:
+Phel is approaching its 1.0 release, but we're still actively refining the language —and yes, breaking changes may happen.
 
-- [VSCode extension](https://github.com/phel-lang/phel-vs-code-extension)
-- [PhpStorm syntax plugin](https://github.com/phel-lang/phel-phpstorm-syntax)
-- [Emacs interactive mode](https://codeberg.org/mmontone/interactive-lang-tools/src/branch/master/backends/phel)
-- [Vim plugin (in progress)](https://github.com/danirod/phel.vim)
+We're building this in the open. That means:
+- Found a bug? File an issue.
+- Got a cool idea? Open a pull request.
+- Want to shape the language's future? Let's talk.
 
-> Details also in the [Editor Support](/documentation/getting-started/#editor-support) section.
+Your feedback, ideas, and code help Phel grow into something great.