feat(starlight): initial commit

This commit is contained in:
LGUG2Z committed 2025-12-26 11:07:34 -08:00
1 parent ef6be4c979
commit 3d3540e606
348 files changed
+28239 -137

No files matched your search

+2
View File
@@ -19,3 +19,5 @@ pnpm-debug.log*
# macOS-specific files
.DS_Store
src/contents/docs/reference/komorebic*.mdx
+3 -48
View File
@@ -1,49 +1,4 @@
# Starlight Starter Kit: Basics
# komorebi-starlight
[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
```
npm create astro@latest -- --template starlight
```
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
## 🚀 Project Structure
Inside of your Astro + Starlight project, you'll see the following folders and files:
```
.
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ └── docs/
│ └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
Static assets, like favicons, can be placed in the `public/` directory.
## 🧞 Commands
All commands are run from the root of the project, from a terminal:
| Command | Action |
| :------------------------ | :----------------------------------------------- |
| `npm install` | Installs dependencies |
| `npm run dev` | Starts local dev server at `localhost:4321` |
| `npm run build` | Build your production site to `./dist/` |
| `npm run preview` | Preview your build locally, before deploying |
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
| `npm run astro -- --help` | Get help using the Astro CLI |
## 👀 Want to learn more?
Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
Experimental unified documentation site for komorebi for Windows and macOS built
with Starlight.
+47 -21
View File
@@ -1,26 +1,52 @@
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import { remarkHeadingId } from "remark-custom-heading-id";
// https://astro.build/config
export default defineConfig({
integrations: [
starlight({
title: 'My Docs',
social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
sidebar: [
{
label: 'Guides',
items: [
// Each item here is one entry in the navigation menu.
{ label: 'Example Guide', slug: 'guides/example' },
],
},
{
label: 'Reference',
autogenerate: { directory: 'reference' },
},
],
}),
],
markdown: {
remarkPlugins: [remarkHeadingId],
},
integrations: [
starlight({
title: "komorebi",
favicon: "/favicon.svg",
social: [
{
icon: "github",
label: "GitHub",
href: "https://github.com/LGUG2Z/komorebi",
},
],
sidebar: [
{
label: "About",
items: [
{ label: "Overview", slug: "about/overview" },
{ label: "Community", slug: "about/community" },
{ label: "Licensing", slug: "about/licensing" },
{ label: "Sponsorship", slug: "about/sponsorship" },
],
},
{
label: "Guides",
items: [
{ label: "Installation", slug: "guides/installation" },
{
label: "License Registration",
slug: "guides/license-registration",
},
{ label: "Quickstart", slug: "guides/quickstart" },
{ label: "Upgrades", slug: "guides/upgrades" },
{ label: "Uninstallation", slug: "guides/uninstallation" },
],
},
{
label: "Reference",
autogenerate: { directory: "reference" },
},
],
}),
],
});
+1108 -3
View File
File diff suppressed because it is too large. Load diff
+10 -6
View File
@@ -3,15 +3,19 @@
"type": "module",
"version": "0.0.1",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"generate:cli-reference": "node scripts/generate-cli-reference.cjs",
"dev": "npm run generate:cli-reference && astro dev",
"start": "npm run generate:cli-reference && astro dev",
"build": "npm run generate:cli-reference && astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/check": "^0.9.6",
"@astrojs/starlight": "^0.37.1",
"astro": "^5.6.1",
"sharp": "^0.34.2"
"astro": "^5.16.6",
"remark-custom-heading-id": "^2.0.0",
"sharp": "^0.34.5",
"typescript": "^5.9.3"
}
}
}
+1 -1
View File
@@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/><style>path{fill:#000}@media (prefers-color-scheme:dark){path{fill:#fff}}</style></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y="0.9em" font-size="90">🍉</text></svg>

Before

Width:  |  Height:  |  Size: 696 B

After

Width:  |  Height:  |  Size: 111 B

+77
View File
@@ -0,0 +1,77 @@
#!/usr/bin/env node
const fs = require("fs");
const path = require("path");
const cliBaseDir = path.join(__dirname, "../src/data/cli");
const windowsDir = path.join(cliBaseDir, "windows");
const macosDir = path.join(cliBaseDir, "macos");
const windowsOutputFile = path.join(
__dirname,
"../src/content/docs/reference/komorebic-windows.mdx",
);
const macosOutputFile = path.join(
__dirname,
"../src/content/docs/reference/komorebic-macos.mdx",
);
// Helper to read markdown files from a directory
function readMarkdownFiles(dir) {
if (!fs.existsSync(dir)) {
return [];
}
return fs
.readdirSync(dir)
.filter((f) => f.endsWith(".md"))
.sort()
.map((file) => ({
name: file.replace(".md", ""),
content: fs.readFileSync(path.join(dir, file), "utf-8"),
}));
}
// Generate Windows reference
const windowsFiles = readMarkdownFiles(windowsDir);
if (windowsFiles.length > 0) {
let mdx = `---
title: komorebic (Windows)
description: Complete reference for all komorebic commands on Windows.
---
This page contains a complete reference of all \`komorebic\` commands on Windows.
`;
for (const { name, content } of windowsFiles) {
mdx += `### \`${name}\`\n\n`;
mdx += content + "\n\n";
}
fs.writeFileSync(windowsOutputFile, mdx);
console.log(
`Generated ${windowsOutputFile} with ${windowsFiles.length} commands`,
);
}
// Generate macOS reference
const macosFiles = readMarkdownFiles(macosDir);
if (macosFiles.length > 0) {
let mdx = `---
title: komorebic (macOS)
description: Complete reference for all komorebic commands on macOS.
---
This page contains a complete reference of all \`komorebic\` commands on macOS.
`;
for (const { name, content } of macosFiles) {
mdx += `### \`${name}\`\n\n`;
mdx += content + "\n\n";
}
fs.writeFileSync(macosOutputFile, mdx);
console.log(
`Generated ${macosOutputFile} with ${macosFiles.length} commands`,
);
}
if (windowsFiles.length === 0 && macosFiles.length === 0) {
console.log("No CLI documentation found in windows or macos directories");
}
+23
View File
@@ -0,0 +1,23 @@
---
title: Community
description: About komorebi community spaces
tableOfContents: false
---
There is a [Discord server](https://discord.gg/mGkn66PHkx) available for
komorebi-related discussion, help, troubleshooting etc.
The Discord server includes the popular [Rice Rice
Baby](https://discord.com/channels/898554690126630914/1260648062158897284) forum
for users to share their desktops and configurations.
There is a [YouTube
channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg) where I post
komorebi development videos, feature previews and release overviews.
Subscribing to the channel (which is monetized as part of the YouTube Partner
Program) and watching videos is a simple and passive way to contribute
financially to the project.
There is an [Awesome List](https://github.com/LGUG2Z/awesome-komorebi) which
showcases the many awesome projects that exist in the komorebi ecosystem.
+48
View File
@@ -0,0 +1,48 @@
---
title: Licensing
description: About the Komorebi License
---
komorebi is [educational source
software](https://lgug2z.com/articles/educational-source-software/).
## Personal Use
komorebi is licensed under the [Komorebi 2.0.0
license](https://github.com/LGUG2Z/komorebi-license), which is a fork of the
[PolyForm Strict 1.0.0
license](https://polyformproject.org/licenses/strict/1.0.0).
On a high level this means that you are free to do whatever you want with
komorebi for personal use other than redistribution, or distribution of new
works (i.e. hard-forks) based on the software.
Anyone is free to make their own fork of komorebi with changes intended either
for personal use or for integration back upstream via pull requests.
## Commercial Use
A dedicated Individual Commercial Use License is available for those who want to
use komorebi at work.
The Individual Commerical Use License adds “Commercial Use” as a “Permitted Use”
for the licensed individual only, for the duration of a valid paid license
subscription only.
All provisions and restrictions enumerated in the [Komorebi
License](https://github.com/LGUG2Z/komorebi-license) continue to apply.
More information, pricing and purchase links for Individual Commercial Use
Licenses [can be found here](https://lgug2z.com/software/komorebi).
Many employers reimburse software licensing costs, so submit a reimbursement
request to your employer with your receipt(s).
With mainstream corporate software reimbursement policies, the Individual
Commercial Use License functions as a mechanism to empower end users to mediate
corporate contributions to the financial sustainability of independent software.
> Extremely poetic to use detection of the presence of corporate spyware as
> leverage for redistribution of wealth, love this. [1]
>
> [1]: https://lobste.rs/s/vd7dgj/normalize_identifying_corporate#c_ufrklw
+53
View File
@@ -0,0 +1,53 @@
---
title: Overview
description: About komorebi
---
komorebi is an educational source cross-platform tiling window manager for
Windows and macOS.
komorebi allows you to control application windows, virtual workspaces and
display monitors with a CLI which can be used with any hotkey software.
komorebi aims to make *as few modifications as possible* to the operating
system and desktop environment by default.
## Design
komorebi only responds to operating system events 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 directly.
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
hotkey daemon --------> komorebic <------> komorebi
```
## Data Model
komorebi holds a list of physical monitors.
A monitor is a rectangle of the available work area which contains one or more
virtual workspaces.
A workspace holds a list of containers.
A container is 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
+23
View File
@@ -0,0 +1,23 @@
---
title: Sponsorship
description: About sponsoring komorebi
tableOfContents: false
---
komorebi is an [educational
source](https://lgug2z.com/articles/educational-source-software/) project, and
one that encourages you to make charitable donations if you find the software to
be useful and have the financial means.
I encourage you to make a charitable donation to the [Palestine Children's
Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery), the [Sameer
Project](https://chuffed.org/project/149178-sameer-project-x-mass-displacement-campaign)
or to contribute to a [Gaza Funds campaign](https://gazafunds.com) before you
consider sponsoring me on GitHub.
## Ways to Sponsor
* [GitHub Sponsors](https://github.com/sponsors/LGUG2Z)
* [Ko-fi](https://ko-fi.com/lgug2z)
* [YouTube Membership](https://www.youtube.com/@LGUG2Z/membership)
* BTC: `bc1qv73wzspc77k46uty4vp85x8sdp24mphvm58f6q`
-11
View File
@@ -1,11 +0,0 @@
---
title: Example Guide
description: A guide in my new Starlight docs site.
---
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
Writing a good guide requires thinking about what your users are trying to do.
## Further reading
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
+174
View File
@@ -0,0 +1,174 @@
---
title: Installation
description: How to install komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Packages are available install via [Scoop](https://scoop.sh/#/apps?q=komorebi)
and [WinGet](https://winget.run/pkg/LGUG2Z/komorebi) on Windows, and
[Homebrew](https://github.com/LGUG2Z/homebrew-tap) and
[Nix](https://github.com/KomoCorp/komorebi-for-mac) on macOS.
You may also build from source on both platforms.
:::note[komorebi for Mac availability]
komorebi for Mac is currently only available in early access to [GitHub Sponsors](https://github.com/sponsors/LGUG2Z) on the $10/month tier.
:::
## Suggested system settings
<Tabs syncKey="platform">
<TabItem label="Windows">
It is 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
```
It is also highly recommended that you enable the "Turn off all unnecessary
animations (when possible)" option in "Control Panel > Ease of Access > Ease of
Access Centre / Make the computer easier to see" for the best performance with
komorebi.
</TabItem>
<TabItem label="macOS">
Go to `System Settings -> Desktop & Dock -> Mission Control -> Displays have
separate Spaces` and disable this option if you are using more than one monitor.
komorebi is scoped to a single macOS space (the one that is active when the
process is started), which means that you can still use other Spaces as if
komorebi were not running at all. If you are using monitors with the above
option enabled, komorebi will only be listening to events from the Space on the
monitor which it was launched on.
Go to `System Settings -> Desktop & Dock -> Mission Control -> Group windows
by application` and disable this option if you like to use mission control.
</TabItem>
</Tabs>
## Installation via Package Managers
:::note[Windows $Env:PATH Issues]
Issues with `komorebi` and related commands not being recognized in the
terminal ultimately come down to the `$Env:PATH` environment variable not being
correctly configured by your package manager and **should not** be raised as
bugs or issues either on the GitHub repository or Discord server.
:::
<Tabs syncKey="package-manager">
<TabItem label="Scoop">
```bash title="Add the extras bucket"
scoop bucket add extras
```
```bash title="Install komorebi and whkd"
scoop install komorebi whkd
```
</TabItem>
<TabItem label="WinGet">
```bash title="Install komorebi and whkd"
winget install LGUG2Z.komorebi
winget install LGUG2Z.whkd
```
:::note
You must restart your terminal after installing with WinGet.
:::
</TabItem>
<TabItem label="Homebrew">
```bash title="Add lgug2z/tap"
brew tap lgug2z/tap
```
```bash title="Install komorebi and skhd"
brew install lgug2z/tap/komorebi-for-mac-nightly
brew install skhd
```
</TabItem>
<TabItem label="Nix">
Ensure that your system Flake is configured to use your GitHub token so that you
can add a private repository as an input.
```nix title="flake.nix"
{
nix = {
settings = {
access-tokens = [
"github.com=YOUR ACCESS TOKEN"
];
};
};
}
```
Add the repository as an input:
```nix title="flake.nix"
{
inputs.komorebi-for-mac.url = "github:KomoCorp/komorebi-for-mac";
}
```
Add the overlay to your system's nixpkgs configuration:
```nix title="flake.nix"
{
pkgs = import nixpkgs {
inherit system;
overlays = [ komorebi-for-mac.overlays.default ];
# the rest of your pkgs configuration
};
}
```
Add `pkgs.komorebi-full` to `environment.systemPackages` (you may also add
`pkgs.komorebi`, `pkgs.komorebic` and `pkgs.komorebi-bar` individually)
```nix title="flake.nix"
{
environment.systemPackages = [
pkgs.komorebi-full
];
}
```
</TabItem>
</Tabs>
## Building From Source
Make sure you have installed [`rustup`](https://rustup.rs), a stable Rust
compiler toolchain, and if compiling on Windows, the Visual Studio [Visual
Studio prerequisites](https://rust-lang.github.io/rustup/installation/windows-msvc.html).
Clone the git repository, enter the directory, and build the following binaries:
```bash title="Build and install the individual binaries"
# Windows and macOS
cargo +stable install --path komorebi --locked
cargo +stable install --path komorebic --locked
cargo +stable install --path komorebi-bar --locked
# Windows only
cargo +stable install --path komorebi-shortcuts --locked
cargo +stable install --path komorebic-no-console --locked
cargo +stable install --path komorebi-gui --locked
```
The binaries will be installed to `$HOME/.cargo/bin`. It is your responsibility
to ensure this directory is in your `$PATH`.
You can follow similar instructions to build
[`whkd`](https://github.com/LGUG2Z/whkd) from source on Windows.
## Offline Installation
Windows users can download the latest
[komorebi](https://github.com/LGUG2Z/komorebi/releases) and
[whkd](https://github.com/LGUG2Z/whkd/releases) MSI installers on an
internet-connected computer, then copy them to an offline machine to install.
@@ -0,0 +1,34 @@
---
title: License Registration
description: A license registration guide for komorebi.
---
komorebi [identifies corporate devices](https://lgug2z.com/articles/normalize-identifying-corporate-devices-in-your-software/) [on a best-effort
basis](https://lobste.rs/s/vd7dgj/normalize_identifying_corporate) through the
detection of mobile device management enrollment.
## License Registration
If you are using komorebi on a device enrolled in mobile device management, you
will receive a pop-up when you run `komorebic start` reminding you that the
[Komorebi License](https://github.com/LGUG2Z/komorebi-license) does not permit
any kind of commercial use.
You can remove this pop-up by running `komorebic license <email>` with the email
associated with your Individual Commercial Use License. A single HTTP request
will be sent with the given email address to verify license validity.
## Students on Windows Machines
If you have an device provided by your educational institution, or a personal
device which you have been forced to enroll in "Bring Your Own Device" (BYOD)
MDM, you can email me (my_github_username _at_ fastmail _dot_ com) from the
address associated with your institution with the subject "komorebi - student
with an MDM device", and I will be able to remove the splash intended for
corporate users
This is currently a manual process - most days this shouldn't take more than
12h, and you will receive an email reply from me when the process is complete.
If you haven't had a reply to your email within 24h you can reach out to me on
[Discord](https://discord.gg/mGkn66PHkx).
+76
View File
@@ -0,0 +1,76 @@
---
title: Quickstart
description: A quickstart guide for komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Tiling window managers in general are very complex pieces of software.
In an attempt to reduce some of the initial configuration burden for users who
are looking to try out the software for the first time, example configurations
are provided and updated whenever appropriate.
Run the following command to download example configuration files for
komorebi, whkd (on Windows) and skhd (on macOS).
Pay attention to the output of the command to see where the example files have
been downloaded.
```shell title="Install the example configurations"
komorebic quickstart
```
:::note[macOS Permissions]
The `quickstart` command will also prompt you to grant komorebi and the terminal
emulator you are start komorebi with the permissions it requires to run, and
will open the following System Settings tabs for you:
* Settings -> Privacy & Security -> Accessibility
* Settings -> Privacy & Security -> Screen & System Audio Recording
komorebi will not run unless it has the required permissions.
:::
## Starting komorebi
<Tabs syncKey="platform">
<TabItem label="Windows">
With the example configurations downloaded, you can now start `komorebi`,
`komorebi-bar` and `whkd`.
```bash title="Start komorebi, komorebi-bar and whkd in the background"
komorebic start --whkd --bar
```
If you decide you don't like the komorebi-bar and want to use a different bar,
you can kill the bar, and next time you start komorebi, omit the `--bar` flag.
```bash title="Kill the komorebi-bar and start komorebi without it"
komorebic kill --bar
komorebic start --whkd
```
</TabItem>
<TabItem label="macOS">
With the example configurations downloaded, you can now start `komorebi`,
`komorebi-bar` and `skhd`.
```bash title="Start komorebi, komorebi-bar in the background"
komorebic start --bar
```
```bash title="Start skhd in the foreground"
skhd --config ~/.config/komorebi/skhdrc
```
If you decide you don't like the komorebi-bar and want to use a different bar,
you can kill the bar, and next time you start komorebi, omit the `--bar` flag.
```bash title="Kill the komorebi-bar and start komorebi without it"
pkill komorebi-bar
komorebic start
```
</TabItem>
</Tabs>
@@ -0,0 +1,54 @@
---
title: Uninstallation
description: How to uninstall komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Before upgrading, ensure that komorebi and the komorebi bar have been stopped.
If you wish to uninstall whkd on Windows or skhd on macOS, ensure they have also
been stopped.
<Tabs syncKey="package-manager">
<TabItem label="Scoop">
```bash title="Uninstall komorebi and whkd"
scoop uninstall komorebi whkd
```
</TabItem>
<TabItem label="WinGet">
```bash title="Uninstall komorebi and whkd"
winget uninstall LGUG2Z.komorebi
winget uninstall LGUG2Z.wkhd
```
</TabItem>
<TabItem label="Homebrew">
```bash title="Uninstall komorebi and skhd"
brew uninstall lgug2z/tap/komorebi-for-mac-nightly
brew uninstall skhd
```
</TabItem>
</Tabs>
Finally, you can run the following commands to clean up files created by the
`quickstart` command and any other runtime files:
<Tabs syncKey="platform">
<TabItem label="Windows">
```bash title="Clean up runtime files"
rm $Env:USERPROFILE/komorebi.json
rm $Env:USERPROFILE/applications.json
rm $Env:USERPROFILE/.config/whkdrc
rm -r -Force $Env:LOCALAPPDATA/komorebi
```
</TabItem>
<TabItem label="macOS">
```bash title="Clean up runtime files"
rm -rf ~/.config/komorebi
rm -rf "~/Library/Application Support/komorebi"
```
</TabItem>
</Tabs>
+39
View File
@@ -0,0 +1,39 @@
---
title: Upgrades
description: How to upgrade komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Before upgrading, ensure that komorebi and the komorebi bar have been stopped.
```bash title="Stop komorebi and komorebi bar"
komorebic stop --bar
```
Once the processes have been stopped, you can upgrade komorebi using your
package manager.
<Tabs syncKey="package-manager">
<TabItem label="Scoop">
```bash title="Upgrade komorebi"
scoop update komorebi
```
</TabItem>
<TabItem label="WinGet">
```bash title="Upgrade komorebi"
winget upgrade LGUG2Z.komorebi
```
</TabItem>
<TabItem label="Homebrew">
```bash title="Upgrade komorebi"
brew update
brew upgrade lgug2z/tap/komorebi-for-mac-nightly
```
</TabItem>
</Tabs>
Once the upgrade is completed you can confirm that you have the latest version
by running `komorebic --version`, and then start it with `komorebic start --whkd --bar`.
+5 -36
View File
@@ -1,40 +1,9 @@
---
title: Welcome to Starlight
description: Get started building your docs site with Starlight.
template: splash # Remove or comment out this line to display the site sidebar on this page.
hero:
tagline: Congrats on setting up a new Starlight project!
image:
file: ../../assets/houston.webp
actions:
- text: Example Guide
link: /guides/example/
icon: right-arrow
- text: Read the Starlight docs
link: https://starlight.astro.build
icon: external
variant: minimal
title: Welcome
description: komorebi - The cross-platform tiling window manager for Windows and macOS
tableOfContents: false
---
import { Card, CardGrid } from '@astrojs/starlight/components';
komorebi is an educational source cross-platform tiling window manager for Windows and macOS.
## Next steps
<CardGrid stagger>
<Card title="Update content" icon="pencil">
Edit `src/content/docs/index.mdx` to see this page change.
</Card>
<Card title="Change page layout" icon="document">
Delete `template: splash` in `src/content/docs/index.mdx` to display a
sidebar on this page.
</Card>
<Card title="Add new content" icon="add-document">
Add Markdown or MDX files to `src/content/docs` to create new pages.
</Card>
<Card title="Configure your site" icon="setting">
Edit your `sidebar` and other config in `astro.config.mjs`.
</Card>
<Card title="Read the docs" icon="open-book">
Learn more in [the Starlight Docs](https://starlight.astro.build/).
</Card>
</CardGrid>
![screenshot](https://user-images.githubusercontent.com/13164844/184027064-f5a6cec2-2865-4d65-a549-a1f1da589abf.png)
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
-11
View File
@@ -1,11 +0,0 @@
---
title: Example Reference
description: A reference page in my new Starlight docs site.
---
Reference pages are ideal for outlining how things work in terse and clear terms.
Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
## Further reading
- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,17 @@
```
Adjust container padding on the focused workspace
Usage: adjust-container-padding <SIZING> <ADJUSTMENT>
Arguments:
<SIZING>
[possible values: increase, decrease]
<ADJUSTMENT>
Pixels to adjust by as an integer
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Adjust workspace padding on the focused workspace
Usage: adjust-workspace-padding <SIZING> <ADJUSTMENT>
Arguments:
<SIZING>
[possible values: increase, decrease]
<ADJUSTMENT>
Pixels to adjust by as an integer
Options:
-h, --help
Print help
```
+19
View File
@@ -0,0 +1,19 @@
```
Set the duration for movement animations in ms
Usage: animation-duration [OPTIONS] <DURATION>
Arguments:
<DURATION>
Desired animation durations in ms
Options:
-a, --animation-type <ANIMATION_TYPE>
Animation type to apply the duration to. If not specified, sets global duration
[possible values: movement]
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Set the frames per second for movement animations
Usage: animation-fps <FPS>
Arguments:
<FPS>
Desired animation frames per second
Options:
-h, --help
Print help
```
+22
View File
@@ -0,0 +1,22 @@
```
Set the ease function for movement animations
Usage: animation-style [OPTIONS]
Options:
-s, --style <STYLE>
Desired ease function for animation
[default: linear]
[possible values: linear, ease-in-sine, ease-out-sine, ease-in-out-sine, ease-in-quad, ease-out-quad, ease-in-out-quad, ease-in-cubic, ease-out-cubic, ease-in-out-cubic, ease-in-quart, ease-out-quart, ease-in-out-quart, ease-in-quint, ease-out-quint, ease-in-out-quint, ease-in-expo, ease-out-expo, ease-in-out-expo, ease-in-circ, ease-out-circ,
ease-in-out-circ, ease-in-back, ease-out-back, ease-in-out-back, ease-in-elastic, ease-out-elastic, ease-in-out-elastic, ease-in-bounce, ease-out-bounce, ease-in-out-bounce]
-a, --animation-type <ANIMATION_TYPE>
Animation type to apply the style to. If not specified, sets global style
[possible values: movement]
-h, --help
Print help
```
+19
View File
@@ -0,0 +1,19 @@
```
Enable or disable movement animations
Usage: animation [OPTIONS] <BOOLEAN_STATE>
Arguments:
<BOOLEAN_STATE>
[possible values: enable, disable]
Options:
-a, --animation-type <ANIMATION_TYPE>
Animation type to apply the state to. If not specified, sets global state
[possible values: movement]
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Generate a JSON Schema for applications.json
Usage: application-specific-configuration-schema
Options:
-h, --help
Print help
```
+24
View File
@@ -0,0 +1,24 @@
```
Set the colour for a window border kind
Usage: border-colour [OPTIONS] <R> <G> <B>
Arguments:
<R>
Red
<G>
Green
<B>
Blue
Options:
-w, --window-kind <WINDOW_KIND>
[default: single]
[possible values: single, stack, monocle, unfocused, unfocused-locked, floating]
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Set the border offset
Usage: border-offset <OFFSET>
Arguments:
<OFFSET>
Desired offset of the window border
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Set the border width
Usage: border-width <WIDTH>
Arguments:
<WIDTH>
Desired width of the window border
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Enable or disable borders
Usage: border <BOOLEAN_STATE>
Arguments:
<BOOLEAN_STATE>
[possible values: enable, disable]
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Cancel a workspace preselect set by the preselect-direction command, if one exists
Usage: cancel-preselect
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Set the layout on the focused workspace
Usage: change-layout <DEFAULT_LAYOUT>
Arguments:
<DEFAULT_LAYOUT>
[possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack, grid, right-main-vertical-stack, scrolling]
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Remove all application association rules for all workspaces
Usage: clear-all-workspace-rules
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Clear all dynamic layout rules for the specified workspace
Usage: clear-named-workspace-layout-rules <WORKSPACE>
Arguments:
<WORKSPACE>
Target workspace name
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Remove all application association rules for a named workspace
Usage: clear-named-workspace-rules <WORKSPACE>
Arguments:
<WORKSPACE>
Name of a workspace
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Clear all session float rules
Usage: clear-session-float-rules
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Clear all dynamic layout rules for the specified workspace
Usage: clear-workspace-layout-rules <MONITOR> <WORKSPACE>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Remove all application association rules for a workspace by monitor and workspace index
Usage: clear-workspace-rules <MONITOR> <WORKSPACE>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Close the focused workspace (must be empty and unnamed)
Usage: close-workspace
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Close the focused window
Usage: close
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Generate komorebic CLI completions for the target shell
Usage: completions <SHELL>
Arguments:
<SHELL>
[possible values: bash, elvish, fish, powershell, zsh]
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Show the path to komorebi.json
Usage: configuration
Options:
-h, --help
Print help
```
+20
View File
@@ -0,0 +1,20 @@
```
Set the container padding for the specified workspace
Usage: container-padding <MONITOR> <WORKSPACE> <SIZE>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
<SIZE>
Pixels to pad with as an integer
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Set the behaviour when moving windows across monitor boundaries
Usage: cross-monitor-move-behaviour <MOVE_BEHAVIOUR>
Arguments:
<MOVE_BEHAVIOUR>
Possible values:
- swap: Swap the window container with the window container at the edge of the adjacent monitor
- insert: Insert the window container into the focused workspace on the adjacent monitor
- no-op: Do nothing if trying to move a window container in the direction of an adjacent monitor
Options:
-h, --help
Print help (see a summary with '-h')
```
@@ -0,0 +1,14 @@
```
Focus the next empty workspace in the given cycle direction (if one exists)
Usage: cycle-empty-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Change focus to the window in the specified cycle direction
Usage: cycle-focus <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Cycle between available layouts
Usage: cycle-layout <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the monitor in the given cycle direction
Usage: cycle-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused window to the monitor in the given cycle direction
Usage: cycle-move-to-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused window to the workspace in the given cycle direction
Usage: cycle-move-to-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused workspace monitor in the given cycle direction
Usage: cycle-move-workspace-to-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Move the focused window in the specified cycle direction
Usage: cycle-move <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Send the focused window to the monitor in the given cycle direction
Usage: cycle-send-to-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Send the focused window to the workspace in the given cycle direction
Usage: cycle-send-to-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Cycle the index of the focused window in the focused stack in the specified cycle direction
Usage: cycle-stack-index <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Cycle the focused stack in the specified cycle direction
Usage: cycle-stack <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the workspace in the given cycle direction
Usage: cycle-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Show the path to komorebi's data directory in $HOME/Library/Application Support
Usage: data-directory
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Unloads and deletes the com.lgug2z.komorebi.plist file in $HOME/Library/LaunchAgents
Usage: disable-autostart
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Set the display index preference for a monitor identified using its display name
Usage: display-index-preference <INDEX_PREFERENCE> <DISPLAY>
Arguments:
<INDEX_PREFERENCE>
Preferred monitor index (zero-indexed)
<DISPLAY>
Display name as identified in komorebic state
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the first managed window matching the given executable
Usage: eager-focus <EXE>
Arguments:
<EXE>
Case-sensitive exe identifier
Options:
-h, --help
Print help
```
+13
View File
@@ -0,0 +1,13 @@
```
Generates and loads the com.lgug2z.komorebi.plist file in $HOME/Library/LaunchAgents
Usage: enable-autostart [OPTIONS]
Options:
-c, --config <CONFIG>
Path to a static configuration JSON file
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Enforce all workspace rules, including initial workspace rules that have already been applied
Usage: enforce-workspace-rules
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Create these many named workspaces for the specified monitor
Usage: ensure-named-workspaces <MONITOR> [NAMES]...
Arguments:
<MONITOR>
Monitor index (zero-indexed)
[NAMES]...
Names of desired workspaces
Options:
-h, --help
Print help
```
+17
View File
@@ -0,0 +1,17 @@
```
Create at least this many workspaces for the specified monitor
Usage: ensure-workspaces <MONITOR> <WORKSPACE_COUNT>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE_COUNT>
Number of desired workspaces
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Fetch the latest version of applications.json from komorebi-application-specific-configuration
Usage: fetch-app-specific-configuration
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Flip the layout on the focused workspace
Usage: flip-layout <AXIS>
Arguments:
<AXIS>
[possible values: horizontal, vertical, horizontal-and-vertical]
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Focus the last focused workspace on the focused monitor
Usage: focus-last-workspace
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Focus the monitor at the current cursor location
Usage: focus-monitor-at-cursor
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Focus the specified workspace on the target monitor
Usage: focus-monitor-workspace <TARGET_MONITOR> <TARGET_WORKSPACE>
Arguments:
<TARGET_MONITOR>
Target monitor index (zero-indexed)
<TARGET_WORKSPACE>
Workspace index on the target monitor (zero-indexed)
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the specified monitor
Usage: focus-monitor <TARGET>
Arguments:
<TARGET>
Target index (zero-indexed)
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Focus the specified workspace
Usage: focus-named-workspace <WORKSPACE>
Arguments:
<WORKSPACE>
Target workspace name
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the specified window index in the focused stack
Usage: focus-stack-window <TARGET>
Arguments:
<TARGET>
Target index (zero-indexed)
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the specified workspace on the focused monitor
Usage: focus-workspace <TARGET>
Arguments:
<TARGET>
Target index (zero-indexed)
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Focus the specified workspace on all monitors
Usage: focus-workspaces <TARGET>
Arguments:
<TARGET>
Target index (zero-indexed)
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Change focus to the window in the specified direction
Usage: focus <OPERATION_DIRECTION>
Arguments:
<OPERATION_DIRECTION>
[possible values: left, right, up, down]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Set container padding on the focused workspace
Usage: focused-workspace-container-padding <SIZE>
Arguments:
<SIZE>
Pixels size to set as an integer
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Set workspace padding on the focused workspace
Usage: focused-workspace-padding <SIZE>
Arguments:
<SIZE>
Pixels size to set as an integer
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Generates a static configuration JSON file based on the current window manager state
Usage: generate-static-config
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Show a JSON representation of the current global state
Usage: global-state
Options:
-h, --help
Print help
```
@@ -0,0 +1,23 @@
```
Set offsets to exclude parts of the work area from tiling
Usage: global-work-area-offset <LEFT> <TOP> <RIGHT> <BOTTOM>
Arguments:
<LEFT>
Size of the left work area offset (set right to left * 2 to maintain right padding)
<TOP>
Size of the top work area offset (set bottom to the same value to maintain bottom padding)
<RIGHT>
Size of the right work area offset
<BOTTOM>
Size of the bottom work area offset
Options:
-h, --help
Print help
```
+17
View File
@@ -0,0 +1,17 @@
```
Add a rule to ignore the specified application
Usage: ignore-rule <IDENTIFIER> <ID>
Arguments:
<IDENTIFIER>
[possible values: exe, class, title, path]
<ID>
Identifier as a string
Options:
-h, --help
Print help
```
@@ -0,0 +1,20 @@
```
Add a rule to associate an application with a named workspace on first show
Usage: initial-named-workspace-rule <IDENTIFIER> <ID> <WORKSPACE>
Arguments:
<IDENTIFIER>
[possible values: exe, class, title, path]
<ID>
Identifier as a string
<WORKSPACE>
Name of a workspace
Options:
-h, --help
Print help
```
@@ -0,0 +1,23 @@
```
Add a rule to associate an application with a workspace on first show
Usage: initial-workspace-rule <IDENTIFIER> <ID> <MONITOR> <WORKSPACE>
Arguments:
<IDENTIFIER>
[possible values: exe, class, title, path]
<ID>
Identifier as a string
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Specify an email associated with an Individual Commercial Use License
Usage: license <EMAIL>
Arguments:
<EMAIL>
Email address associated with an Individual Commercial Use License
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Load the resize layout dimensions from a file
Usage: load-resize <PATH>
Arguments:
<PATH>
File from which the resize layout dimensions should be loaded
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Tail komorebi's process logs (cancel with Ctrl-C)
Usage: log
Options:
-h, --help
Print help
```
+17
View File
@@ -0,0 +1,17 @@
```
Add a rule to always manage the specified application
Usage: manage-rule <IDENTIFIER> <ID>
Arguments:
<IDENTIFIER>
[possible values: exe, class, title, path]
<ID>
Identifier as a string
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Force komorebi to manage the focused window
Usage: manage
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Minimize the focused window
Usage: minimize
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Show information about connected monitors
Usage: monitor-information
Options:
-h, --help
Print help
```
@@ -0,0 +1,26 @@
```
Set offsets for a monitor to exclude parts of the work area from tiling
Usage: monitor-work-area-offset <MONITOR> <LEFT> <TOP> <RIGHT> <BOTTOM>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<LEFT>
Size of the left work area offset (set right to left * 2 to maintain right padding)
<TOP>
Size of the top work area offset (set bottom to the same value to maintain bottom padding)
<RIGHT>
Size of the right work area offset
<BOTTOM>
Size of the bottom work area offset
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Enable or disable mouse follows focus on all workspaces
Usage: mouse-follows-focus <BOOLEAN_STATE>
Arguments:
<BOOLEAN_STATE>
[possible values: enable, disable]
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Move the focused window to the last focused monitor workspace
Usage: move-to-last-workspace
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Move the focused window to the specified monitor workspace
Usage: move-to-monitor-workspace <TARGET_MONITOR> <TARGET_WORKSPACE>
Arguments:
<TARGET_MONITOR>
Target monitor index (zero-indexed)
<TARGET_WORKSPACE>
Workspace index on the target monitor (zero-indexed)
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Move the focused window to the specified monitor
Usage: move-to-monitor <TARGET>
Arguments:
<TARGET>
Target index (zero-indexed)
Options:
-h, --help
Print help
```
Loaded 100 of 348 files, more files were not shown because too many files have changed in this diff. Show more