Merge pull request #116 from phel-lang/docs/improve-getting-started

Simplify getting started page

Author: Chemaclass

README.md

@@ -31,4 +31,4 @@ zola serve # build & serve
 
 ```bash
 zola build # build & publish
-```
+```

content/_index.md

@@ -68,7 +68,7 @@ docker run -it --rm phellang/repl
 
 ## Get Started with Phel in Minutes
 
-All you need is [PHP >=8.2](https://www.php.net/) and [Composer](https://getcomposer.org/). 
+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.
 

content/documentation/getting-started.md

@@ -1,132 +1,131 @@
 +++
-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.
-
-
-## Manually initialize a new project using Composer
+> For web projects: [web-skeleton](https://github.com/phel-lang/web-skeleton)  
 
-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.
+Optional config (`phel-config.php`):
 
-Then, create a new directory `src` with a file `main.phel` inside this directory.
-
-```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
+## Run Code
+
+**From CLI:**
 
-There are two ways to run the code: from the command line and with a PHP Server.
+```bash
+vendor/bin/phel run src/main.phel
+```
 
-### From the Command line
+**With PHP Server:**
 
-Code can be executed from the command line by calling the `vendor/bin/phel run` command, followed by the file path or namespace:
+```php
+<?php
+require __DIR__ . '/../vendor/autoload.php';
+\Phel\Phel::run(__DIR__ . '/../', 'hello-world\\main');
+```
 
 ```bash
-vendor/bin/phel run src/main.phel
-# or
-vendor/bin/phel run hello-world\\main
-# or
-vendor/bin/phel run "hello-world\main"
+php -S localhost:8000 ./src/index.php
 ```
 
-The output will be:
+> 📘 [More on running code](/documentation/cli-commands#run-a-script)
+
+## REPL
 
+```bash
+vendor/bin/phel repl
 ```
-Hello, World!
+
+Try:
+
+```phel
+(def name "World")
+(println "Hello" name)
 ```
 
-### With a PHP Server
+> 📘 [More on REPL](/documentation/repl)
 
-> Check the [web-skeleton project on GitHub](https://github.com/phel-lang/web-skeleton).
+## Debugging
 
-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.
+```phel
+(php/dump (+ 40 2))
+```
+
+Enable temp files in `phel-config-local.php`:
 
 ```php
-// src/index.php
 <?php
+return (require __DIR__ . '/phel-config.php')
+  ->setKeepGeneratedTempFiles(true);
+```
 
-use Phel\Phel;
-
-$projectRootDir = __DIR__ . '/../';
+> 📘 [More on debugging](/documentation/debug)
 
-require $projectRootDir . 'vendor/autoload.php';
+## Build & Deploy
 
-Phel::run($projectRootDir, 'hello-world\\main');
+```bash
+vendor/bin/phel build
+php out/index.php
 ```
 
-The PHP Server can now be started.
+> 📘 [More on build](/documentation/cli-commands/#build-the-project)
+
+## Testing
 
 ```bash
-# Start server
-php -S localhost:8000 ./src/index.php
+vendor/bin/phel test --filter foo
 ```
 
-In the browser, the URL `http://localhost:8000` will now print "Hello, World!".
-
-> 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).
+> 📘 [More on testing](/documentation/testing)
 
-## Launch the REPL
+## Handy Macros
 
-To try Phel you can run a REPL by executing the `./vendor/bin/phel repl` command.
+```phel
+(when condition (println "if true"))
+(-> {:name "Phel"} (:name) (str "Lang"))
+```
 
-> Read more about the [REPL](/documentation/repl) in its own chapter.
+> 📘 [More on macros](/documentation/macros)
 
-## 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)