docs: restructure

4 files changed, 311 insertions, 0 deletions

diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md
new file mode 100644
index 0000000..ef5c6e8
--- /dev/null
+++ b/docs/guide/getting-started/installation.md
@@ -0,0 +1,69 @@
+# Installation
+
+## Nix
+
+maintainer: [@Aylur](https://github.com/Aylur)
+
+Read more about it on the [nix page](./nix#astal)
+
+## Arch
+
+maintainer: [@kotontrion](https://github.com/kotontrion)
+
+:::code-group
+
+```sh [Core Library]
+yay -S libastal-git
+```
+
+```sh [Every Library]
+yay -S libastal-meta
+```
+
+:::
+
+## Bulding libastal from source
+
+1. Clone the repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/core
+```
+
+2. Install the following dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala gtk3 gtk-layer-shell gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libgtk3-dev libgtk-layer-shell-dev gobject-introspection
+```
+
+:::
+
+3. Build and install with `meson`
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+meson install -C build
+```
+
+:::
diff --git a/docs/guide/getting-started/introduction.md b/docs/guide/getting-started/introduction.md
new file mode 100644
index 0000000..92d2ff1
--- /dev/null
+++ b/docs/guide/getting-started/introduction.md
@@ -0,0 +1,23 @@
+# Introduction
+
+## What is Astal?
+
+Astal (_meaning "desk"_) is a bundle of libraries built using [GLib](https://docs.gtk.org/glib/) in Vala and C.
+The core library [libastal](https://aylur.github.io/libastal) has some Gtk widgets that come packaged,
+the most important one is the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell).
+This is what allows us to use Gtk as shell components on Wayland.
+libastal also comes with some utility functions such as running external processes,
+reading, writing and monitoring files.
+
+## Why Astal?
+
+What makes Astal convenient to use is not the core library, as it could easily be replaced
+by the standard library of any of your favorite language that has bindings to Gtk, it is the
+accompanying libraries (_formerly known as "services" in AGS_)
+
+Have you ever wanted to write a custom bar, custom notification popups
+or an applauncher, but gave up because writing a workspace widget,
+implementing the notification daemon or handling a search filter was too much of a hassle?
+
+Astal libraries have you [covered](/guide/libraries/references), you don't have to worry about these,
+you just define the layout, style it with CSS and that's it.
diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md
new file mode 100644
index 0000000..2b04bdc
--- /dev/null
+++ b/docs/guide/getting-started/nix.md
@@ -0,0 +1,154 @@
+# Nix
+
+## Astal
+
+Using Astal on Nix will require you to package your project.
+
+:::code-group
+
+```nix [<i class="devicon-lua-plain"></i> Lua]
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    astal = {
+      url = "github:aylur/astal";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, astal }: let
+    system = "x86_64-linux";
+    pkgs = nixpkgs.legacyPackages.${system};
+  in {
+    packages.${system}.default = astal.lib.mkLuaPacakge {
+      inherit pkgs;
+      src = ./path/to/project; # should contain init.lua
+
+      # add extra glib packages or binaries
+      extraPackages = [
+        astal.packages.${system}.battery
+        pkgs.dart-sass
+      ];
+    };
+  };
+}
+```
+
+```nix [<i class="devicon-python-plain"></i> Python]
+# Not documented yet
+```
+
+```nix [<i class="devicon-vala-plain"></i> Vala]
+# keep in mind that this is just the nix derivation
+# and you still have to use some build tool like meson
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    astal.url = "github:aylur/astal";
+  };
+
+  outputs = { self, nixpkgs, astal }: let
+    system = "x86_64-linux";
+    pkgs = nixpkgs.legacyPackages.${system};
+  in {
+    packages.${system} = {
+      default = pkgs.stdenv.mkDerivation {
+        name = "my-shell";
+        src = ./.;
+
+        nativeBuildInputs = with pkgs; [
+          meson
+          ninja
+          pkg-config
+          vala
+          gobject-introspection
+        ];
+
+        # add extra packages
+        buildInputs = [
+          astal.packages.${system}.astal
+        ];
+      };
+    };
+  };
+}
+```
+
+:::
+
+## AGS
+
+The recommended way to use AGS on NixOS is through the home-manager module.
+
+Example content of a `flake.nix` file that contains your `homeConfigurations`.
+
+<!--TODO: remove v2 after merge-->
+
+:::code-group
+
+```nix [<i class="devicon-nixos-plain"></i> flake.nix]
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    home-manager = {
+      url = "github:nix-community/home-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    # add ags https://github.com/Aylur/ags/pull/504
+    ags.url = "github:aylur/ags/v2";
+  };
+
+  outputs = { home-manager, nixpkgs, ... }@inputs:
+  let
+    system = "x86_64-linux";
+  in
+  {
+    homeConfigurations."${username}" = home-manager.lib.homeManagerConfiguration {
+      pkgs = import nixpkgs { inherit system; };
+
+      # pass inputs as specialArgs
+      extraSpecialArgs = { inherit inputs; };
+
+      # import your home.nix
+      modules = [ ./home-manager/home.nix ];
+    };
+  };
+}
+```
+
+:::
+
+Example content of `home.nix` file
+
+:::code-group
+
+```nix [<i class="devicon-nixos-plain"></i> home.nix]
+{ inputs, pkgs, ... }:
+{
+  # add the home manager module
+  imports = [ inputs.ags.homeManagerModules.default ];
+
+  programs.ags = {
+    enable = true;
+    configDir = ../ags;
+
+    # additional packages to add to gjs's runtime
+    extraPackages = with pkgs; [
+      inputs.ags.packages.${pkgs.system}.battery
+      fzf
+    ];
+  };
+}
+```
+
+:::
+
+AGS by default only includes the core `libastal` library.
+If you want to include any other [library](../libraries/references) you have to add them to `extraPackages`.
+You can also add binaries which will be added to `$PATH`.
+
+:::warning
+The `configDir` option symlinks the given path to `~/.config/ags`.
+If you already have your source code there leave it as `null`.
+:::
diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md
new file mode 100644
index 0000000..634bad0
--- /dev/null
+++ b/docs/guide/getting-started/supported-languages.md
@@ -0,0 +1,65 @@
+# Supported Languages
+
+## JavaScript
+
+The main intended usage of Astal is in TypeScript with [AGS](/guide/ags/first-widgets).
+It supports JSX and has a state management solution similar to web frameworks.
+Only a minimal knowledge of JavaScript's syntax is needed to get started.
+
+:::info
+The runtime is [GJS](https://gitlab.gnome.org/GNOME/gjs) and **not** nodejs
+:::
+
+Examples:
+
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/js/simple-bar)
+![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
+
+## Lua
+
+Similar to how there is a [TypeScript](https://github.com/Aylur/astal/tree/main/core/gjs) lib for GJS, there is also an accompanying library for [Lua](https://github.com/Aylur/astal/tree/main/core/lua).
+<!--TODO: open issue and link performance issue-->
+Unfortunately, I have encountered very heavy [performance issues](https://github.com/aylur/astal) with [lgi](https://github.com/lgi-devs/lgi),
+and so currently I don't recommend using Lua for full desktop shells, but only for static
+components that don't render child nodes dynamically, bars and panels for example.
+
+Examples:
+
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/lua/simple-bar)
+![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
+
+## Python
+
+There was a WIP [library for python](https://github.com/aylur/astal/tree/feat/python), to make it behave similar to the above two
+but I don't plan on finishing it, because I'm not a fan of python.
+If you are interested in picking it up, feel free to open a PR.
+Nonetheless you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it.
+
+Examples:
+
+- [Starter Bar](https://github.com/Aylur/astal/tree/main/examples/py/starter-bar)
+
+## Vala
+
+Vala is a language that simply put uses C# syntax and compiles to C.
+It is the language most of Astal is written in. I would still recommend
+using TypeScript or Lua over Vala as they don't need a build step.
+
+Examples:
+
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/vala/simple-bar)
+![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
+
+## C
+
+I don't recommend using C as it requires quite a lot of boilerplate, both for
+build step and code.
+
+Examples:
+
+- TODO
+
+## Other languages
+
+There a few more that supports gobject-introspection, most notably Haskell, Rust and C++.
+If you are interested and feel like contributing, PRs are welcome for bindings, and examples.