From 6f08ec1cb3614ee5be0f59fb4bed8156e7495b92 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Fri, 12 Jan 2024 18:40:58 -0800 Subject: [PATCH] docs(mkdocs): start building dedicated site --- docs/design.md | 40 ++++++++++++++++++++++++++++++ docs/getting-started.md | 37 ++++++++++++++++++++++++++++ docs/index.md | 15 +++++++++++ docs/install/build-from-source.md | 19 ++++++++++++++ docs/install/scoop.md | 20 +++++++++++++++ docs/install/winget.md | 16 ++++++++++++ mkdocs.yml | 41 +++++++++++++++++++++++++++++++ 7 files changed, 188 insertions(+) create mode 100644 docs/design.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/install/build-from-source.md create mode 100644 docs/install/scoop.md create mode 100644 docs/install/winget.md create mode 100644 mkdocs.yml diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..dd494990 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,40 @@ +--- +hide: + - toc +--- + +## Description + +_komorebi_ only responds to [WinEvents](https://docs.microsoft.com/en-us/windows/win32/winauto/event-constants) and the +messages it receives on a dedicated socket. + +_komorebic_ is a CLI that writes messages on _komorebi_'s socket. + +_komorebi_ doesn't handle any keyboard or mouse inputs; a third party program (e.g. +[whkd](https://github.com/LGUG2Z/whkd)) is needed in order to translate keyboard and mouse events to _komorebic_ commands. + +This architecture, popularised by [_bspwm_](https://github.com/baskerville/bspwm) on Linux and +[_yabai_](https://github.com/koekeishiya/yabai) on macOS, is outlined as follows: + + +``` + PROCESS SOCKET +whkd/ahk --------> komorebic <------> komorebi +``` + +## Data Model + +_komorebi_ holds a list of physical monitors. + +A monitor is just a rectangle of the available work area which contains one or more virtual workspaces. + +A workspace holds a list of containers. + +A container is just a rectangle where one or more application windows can be displayed. + +This means that: + +- Every monitor has its own collection of virtual workspaces +- Workspaces only know about containers and their dimensions, not about individual application windows +- Every application window must belong to a container, even if that container only contains one application window +- Many application windows can be stacked and cycled through in the same container within a workspace diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..7af77b00 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,37 @@ +--- +hide: + - navigation +--- +## Installation + +Komorebi is available pre-built to install via +[Scoop](https://scoop.sh/#/apps?q=komorebi) and +[WinGet](https://winget.run/pkg/LGUG2Z/komorebi), and you may also built +it from [source](https://github.com/LGUG2Z/komorebi) if you would prefer. + + - [Scoop](install/scoop.md) + - [WinGet](install/winget.md) + - [Build from source](install/source.md) + +## Getting Example Configurations + +Run the following command to download example configuration files for +`komorebi` and `whkd`. Pay attention to the output of the command to see +where the example files have been downloaded. + +```powershell +komorebic quickstart +``` + +## Starting Komorebi + +Run the following command to start `komorebi` and `whkd` with the example +configurations. + +It is important that you run this command for the first time without +making any modifications to the example configurations to validate that +you have a working installation of both `komorebi` and `whkd`. + +```powershell +komorebic start --whkd +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..45c1d80c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +# Komorebi + +![screenshot](https://user-images.githubusercontent.com/13164844/184027064-f5a6cec2-2865-4d65-a549-a1f1da589abf.png) + +_komorebi_ is a tiling window manager that works as an extension to +Microsoft's [Desktop Window Manager](https://docs.microsoft.com/en-us/windows/win32/dwm/dwm-overview) in Windows 10 and +above. + +_komorebi_ allows you to control application windows, virtual workspaces and display monitors with a CLI which can be +used with third-party software such as [AutoHotKey](https://github.com/Lexikos/AutoHotkey_L) to set user-defined +keyboard shortcuts. + +_komorebi_ aims to make _as few modifications as possible_ to the operating system and desktop environment by default. +Users are free to make such modifications in their own configuration files for _komorebi_, but these will remain +opt-in and off-by-default for the foreseeable future. diff --git a/docs/install/build-from-source.md b/docs/install/build-from-source.md new file mode 100644 index 00000000..a1b08b2e --- /dev/null +++ b/docs/install/build-from-source.md @@ -0,0 +1,19 @@ +## Installing From Source + +First, [install `rustup`](https://rustup.rs/) to get the `rust` compiler installed on your system, and make sure you have installed the [Visual Studio prerequisites](https://rust-lang.github.io/rustup/installation/windows-msvc.html). + +Then clone the git repository. + +```powershell +git clone https://github.com/LGUG2Z/komorebi.git +``` + +Once inside the repository, you will need to build and install three separate binaries. + +```powershell +cargo +stable install --path komorebi --locked +cargo +stable install --path komorebic --locked +cargo +stable install --path komorebic-no-console --locked +``` + +If the binaries have been built and added to your `$PATH` correctly, you should see some output when running `komorebi --help` and `komorebic --help` diff --git a/docs/install/scoop.md b/docs/install/scoop.md new file mode 100644 index 00000000..efc73561 --- /dev/null +++ b/docs/install/scoop.md @@ -0,0 +1,20 @@ +## Installing with Scoop + +It highly recommended that you enable support for long paths in Windows by running the following command in an Administrator Terminal before installing komorebi. + +```powershell +Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 +``` +### Add the Extras bucket +``` +scoop bucket add extras +``` + +### Install komorebi and whkd + +This command installs `komorebi` and `whkd`. +``` +scoop install komorebi whkd +``` + +Once komorebi is installed, proceed to get the [example configurations](../getting-started.html#getting-example-configurations). diff --git a/docs/install/winget.md b/docs/install/winget.md new file mode 100644 index 00000000..3c547aaa --- /dev/null +++ b/docs/install/winget.md @@ -0,0 +1,16 @@ +## Installing with Scoop + +It highly recommended that you enable support for long paths in Windows by running the following command in an Administrator Terminal before installing komorebi. + +```powershell +Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 +``` +### Install komorebi and whkd + +This command installs `komorebi` and `whkd`. +``` +winget install LGUG2Z.komorebi +winget install LGUG2Z.whkd +``` + +Once komorebi is installed, proceed to get the [example configurations](../getting-started.html#getting-example-configurations). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..6f0c978c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,41 @@ +copyright: Copyright © 2020-Present LGUG2Z +use_directory_urls: false +site_name: Komorebi +site_description: The Tiling Window Manager for Windows +repo_url: https://github.com/LGUG2Z/komorebi +repo_name: LGUG2Z/komorebi +docs_dir: docs +theme: + name: material + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: deep purple + accent: deep purple + toggle: + icon: material/weather-sunny + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: deep purple + accent: purple + toggle: + icon: material/weather-night + name: Switch to light mode + features: + - content.action.edit + - content.action.view + - content.code.copy + - content.tabs.link + - navigation.footer + - navigation.indexes + - navigation.tabs + - navigation.tabs.sticky + - navigation.tracking + - navigation.top + - search.highlight + - search.share + - search.suggest + - toc.follow