From 0a687f808d94764a22c8e7eb8375a5c0d1bfdfc7 Mon Sep 17 00:00:00 2001 From: Ruixi-rebirth Date: Tue, 12 May 2026 15:34:14 +0800 Subject: [PATCH 1/5] feat(nix): generate module options docs and sync to website - Add nix/generate-hm-options.nix to export HM and NixOS module options as JSON via nixosOptionsDoc - Expose hm-options-json and nixos-options-json packages in flake.nix - Add CI workflow to auto-build and push JSONs to mangowm.github.io on module changes - Add missing description to hm-modules enable option --- .github/workflows/sync-nix-options.yml | 59 ++++++++++++++++++++++++++ .gitignore | 1 + flake.nix | 8 ++++ nix/generate-options.nix | 28 ++++++++++++ nix/hm-modules.nix | 1 + 5 files changed, 97 insertions(+) create mode 100644 .github/workflows/sync-nix-options.yml create mode 100644 nix/generate-options.nix diff --git a/.github/workflows/sync-nix-options.yml b/.github/workflows/sync-nix-options.yml new file mode 100644 index 00000000..3e05f0e1 --- /dev/null +++ b/.github/workflows/sync-nix-options.yml @@ -0,0 +1,59 @@ +name: Sync Nix module options + +on: + push: + branches: [main] + paths: + - nix/hm-modules.nix + - nix/nixos-modules.nix + - nix/generate-options.nix + - flake.nix + - flake.lock + +concurrency: + group: sync-nix-options + cancel-in-progress: true + +jobs: + sync-nix-options: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - uses: cachix/install-nix-action@v30 + with: + extra_nix_config: | + experimental-features = nix-command flakes + + - name: Build options JSONs + run: | + HM_OUT=$(nix build .#hm-options-json --no-link --print-out-paths) + NIXOS_OUT=$(nix build .#nixos-options-json --no-link --print-out-paths) + cp "$HM_OUT/share/doc/nixos/options.json" /tmp/hm-options.json + cp "$NIXOS_OUT/share/doc/nixos/options.json" /tmp/nixos-options.json + + - name: Checkout website + uses: actions/checkout@v4 + with: + repository: mangowm/mangowm.github.io + path: website + token: ${{ secrets.WEBSITE_SYNC_TOKEN }} + fetch-depth: 1 + + - name: Copy JSONs to website + run: | + cp /tmp/hm-options.json website/apps/web/src/hm-options.json + cp /tmp/nixos-options.json website/apps/web/src/nixos-options.json + + - name: Commit and push + working-directory: website + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add apps/web/src/hm-options.json apps/web/src/nixos-options.json + git diff --staged --quiet || git commit \ + -m "nix: update module options JSON" \ + -m "${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}" + git push diff --git a/.gitignore b/.gitignore index 7681f948..274cc4ee 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ /.cache /.vscode /result +/result-* config.h mango mango.o diff --git a/flake.nix b/flake.nix index b7158bbd..33b97c9b 100644 --- a/flake.nix +++ b/flake.nix @@ -43,6 +43,14 @@ }; packages = { inherit mango; + hm-options-json = pkgs.callPackage (import ./nix/generate-options.nix self) { + module = ./nix/hm-modules.nix; + optionPrefix = "wayland.windowManager.mango."; + }; + nixos-options-json = pkgs.callPackage (import ./nix/generate-options.nix self) { + module = ./nix/nixos-modules.nix; + optionPrefix = "programs.mango."; + }; }; devShells.default = mango.overrideAttrs shellOverride; formatter = pkgs.alejandra; diff --git a/nix/generate-options.nix b/nix/generate-options.nix new file mode 100644 index 00000000..c2b87a4f --- /dev/null +++ b/nix/generate-options.nix @@ -0,0 +1,28 @@ +self: +{ + pkgs, + lib ? pkgs.lib, + module, + optionPrefix, +}: +let + eval = lib.evalModules { + modules = [ + (import module self) + { _module.check = false; } + ]; + specialArgs = { inherit pkgs; }; + }; + + optionsDoc = pkgs.nixosOptionsDoc { + options = eval.options; + transformOptions = + opt: + opt + // { + visible = opt.visible && !opt.internal; + name = lib.removePrefix optionPrefix opt.name; + }; + }; +in +optionsDoc.optionsJSON diff --git a/nix/hm-modules.nix b/nix/hm-modules.nix index f00d9c68..f9a341a3 100644 --- a/nix/hm-modules.nix +++ b/nix/hm-modules.nix @@ -22,6 +22,7 @@ in enable = mkOption { type = types.bool; default = false; + description = "Whether to enable mangowm, a Wayland compositor based on dwl."; }; package = lib.mkOption { type = lib.types.package; From c3ec4c61420cfd0bfe8a10febffe18c76459e7c8 Mon Sep 17 00:00:00 2001 From: atheeq <168955553+xtheeq@users.noreply.github.com> Date: Tue, 12 May 2026 19:48:45 +0530 Subject: [PATCH 2/5] =?UTF-8?q?refactor(nix):=20replace=20sync=20nix=20opt?= =?UTF-8?q?ions=20with=20direct=20md=20generation=20to=20=E2=80=A6=20(#1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(nix): replace sync nix options with direct md generation to docs * fix(docs): add trailing comman in meta * fix(ci): sort nix options and fix default value check --- .github/scripts/generate-nix-options-docs.py | 80 +++++++++++++++++++ .../workflows/generate-nix-options-docs.yml | 58 ++++++++++++++ .github/workflows/sync-nix-options.yml | 59 -------------- .gitignore | 1 - docs/meta.json | 1 + nix/hm-modules.nix | 1 - 6 files changed, 139 insertions(+), 61 deletions(-) create mode 100755 .github/scripts/generate-nix-options-docs.py create mode 100644 .github/workflows/generate-nix-options-docs.yml delete mode 100644 .github/workflows/sync-nix-options.yml diff --git a/.github/scripts/generate-nix-options-docs.py b/.github/scripts/generate-nix-options-docs.py new file mode 100755 index 00000000..23cd3b90 --- /dev/null +++ b/.github/scripts/generate-nix-options-docs.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +""" +Converts NixOS options JSON into clean, table-formatted Markdown. +""" + +import json +import sys +import re + +def clean_description(desc: str) -> str: + """Removes Nix tags, fixes dangling periods, and formats blockquotes.""" + if not desc: + return "*No description provided.*" + + desc = re.sub(r'\{[a-zA-Z]+\}', '', desc).replace('\n.', '.') + + lines = desc.splitlines() + cleaned = [] + in_note = False + + for line in lines: + if line.startswith("::: {.note"): + in_note = True + cleaned.append("> **Note:**\n>") + elif line.startswith(":::"): + in_note = False + else: + cleaned.append(f"> {line}" if in_note else line) + + return "\n".join(cleaned) + +def format_default_value(default_data) -> str: + """Safely formats the default value, handling HTML escaping for tables.""" + if default_data is None: + return "*None*" + + val_text = default_data.get("text", "") if isinstance(default_data, dict) and default_data.get("_type") == "literalExpression" else str(default_data) + val_text = val_text.replace('|', '|') + + if '\n' in val_text: + safe_html = val_text.replace('<', '<').replace('>', '>').replace('\n', '
') + return f"{safe_html}" + + return f"`{val_text}`" + +def main(): + if len(sys.argv) != 4: + sys.exit("Usage: format_docs.py ") + + input_json, output_md, title = sys.argv[1:4] + + with open(input_json, 'r', encoding='utf-8') as f: + data = json.load(f) + + with open(output_md, 'a', encoding='utf-8') as out: + out.write(f"## {title}\n\n") + + for key, opt in sorted(data.items()): + if key.startswith("_module"): + continue + + desc = clean_description(opt.get("description", "")) + opt_type = str(opt.get("type", "unknown")).replace('|', '|') + default_val = format_default_value(opt.get("default")) + + markdown_block = ( + f"### `{key}`\n\n" + f"{desc}\n\n" + f"| Attribute | Value |\n" + f"| :--- | :--- |\n" + f"| **Type** | `{opt_type}` |\n" + f"| **Default** | {default_val} |\n\n" + f"---\n\n" + ) + out.write(markdown_block) + + print(f"Appended {title} to {output_md} successfully.") + +if __name__ == "__main__": + main() diff --git a/.github/workflows/generate-nix-options-docs.yml b/.github/workflows/generate-nix-options-docs.yml new file mode 100644 index 00000000..e5fd0df2 --- /dev/null +++ b/.github/workflows/generate-nix-options-docs.yml @@ -0,0 +1,58 @@ +name: Generate Nix Options Docs + +on: + push: + paths: + - 'nix/**-modules.nix' + - 'nix/generate-options.nix' + - 'flake.nix' + pull_request: + paths: + - 'nix/**-modules.nix' + +jobs: + update-docs: + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + + - name: Install Nix + uses: cachix/install-nix-action@v30 + with: + extra_nix_config: | + experimental-features = nix-command flakes + + - name: Build Options JSON + run: | + nix build .#nixos-options-json --out-link result-nixos + nix build .#hm-options-json --out-link result-hm + + - name: Format to Markdown + run: | + OUTPUT_FILE="docs/nix-options.md" + + cat << 'EOF' > $OUTPUT_FILE + --- + title: Nix Module Options + description: NixOS and Home Manager configuration options for mangowm. + --- + + > **Note:** This document is automatically generated from the Nix module source code. + + EOF + + python3 ./.github/scripts/generate-nix-options-docs.py result-nixos/share/doc/nixos/options.json $OUTPUT_FILE "NixOS Module Options" + python3 ./.github/scripts/generate-nix-options-docs.py result-hm/share/doc/nixos/options.json $OUTPUT_FILE "Home Manager Options" + + - name: Auto-commit changes + uses: stefanzweifel/git-auto-commit-action@v5 + with: + commit_message: "docs: auto-generate Nix module options" + file_pattern: 'docs/*-options.md' + branch: ${{ github.head_ref }} diff --git a/.github/workflows/sync-nix-options.yml b/.github/workflows/sync-nix-options.yml deleted file mode 100644 index 3e05f0e1..00000000 --- a/.github/workflows/sync-nix-options.yml +++ /dev/null @@ -1,59 +0,0 @@ -name: Sync Nix module options - -on: - push: - branches: [main] - paths: - - nix/hm-modules.nix - - nix/nixos-modules.nix - - nix/generate-options.nix - - flake.nix - - flake.lock - -concurrency: - group: sync-nix-options - cancel-in-progress: true - -jobs: - sync-nix-options: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 1 - - - uses: cachix/install-nix-action@v30 - with: - extra_nix_config: | - experimental-features = nix-command flakes - - - name: Build options JSONs - run: | - HM_OUT=$(nix build .#hm-options-json --no-link --print-out-paths) - NIXOS_OUT=$(nix build .#nixos-options-json --no-link --print-out-paths) - cp "$HM_OUT/share/doc/nixos/options.json" /tmp/hm-options.json - cp "$NIXOS_OUT/share/doc/nixos/options.json" /tmp/nixos-options.json - - - name: Checkout website - uses: actions/checkout@v4 - with: - repository: mangowm/mangowm.github.io - path: website - token: ${{ secrets.WEBSITE_SYNC_TOKEN }} - fetch-depth: 1 - - - name: Copy JSONs to website - run: | - cp /tmp/hm-options.json website/apps/web/src/hm-options.json - cp /tmp/nixos-options.json website/apps/web/src/nixos-options.json - - - name: Commit and push - working-directory: website - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git add apps/web/src/hm-options.json apps/web/src/nixos-options.json - git diff --staged --quiet || git commit \ - -m "nix: update module options JSON" \ - -m "${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}" - git push diff --git a/.gitignore b/.gitignore index 274cc4ee..7681f948 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ /.cache /.vscode /result -/result-* config.h mango mango.o diff --git a/docs/meta.json b/docs/meta.json index 74818a9d..8c10c621 100644 --- a/docs/meta.json +++ b/docs/meta.json @@ -11,6 +11,7 @@ "window-management", "bindings", "---Reference---", + "nix-options", "ipc", "faq" ] diff --git a/nix/hm-modules.nix b/nix/hm-modules.nix index f9a341a3..f00d9c68 100644 --- a/nix/hm-modules.nix +++ b/nix/hm-modules.nix @@ -22,7 +22,6 @@ in enable = mkOption { type = types.bool; default = false; - description = "Whether to enable mangowm, a Wayland compositor based on dwl."; }; package = lib.mkOption { type = lib.types.package; From d5db98cfb774fdcbc6af174d4a6a59fba94e2e54 Mon Sep 17 00:00:00 2001 From: Ruixi-rebirth <ruixirebirth@gmail.com> Date: Tue, 12 May 2026 22:12:07 +0800 Subject: [PATCH 3/5] fix(scripts): improve nix options doc generator - Restore missing description on hm enable option (fixes nix build warning) - Rewrite format_default_value into format_value with example support and nix code blocks - Fix Nix markup stripping: {tag}`content` now preserves backtick content - Generalize ::: block handling beyond {.note} to any block type - Switch output from Markdown table to labeled fields format --- .github/scripts/generate-nix-options-docs.py | 130 +++++++++++------- .../workflows/generate-nix-options-docs.yml | 19 +-- nix/hm-modules.nix | 1 + 3 files changed, 87 insertions(+), 63 deletions(-) diff --git a/.github/scripts/generate-nix-options-docs.py b/.github/scripts/generate-nix-options-docs.py index 23cd3b90..6f5d35bd 100755 --- a/.github/scripts/generate-nix-options-docs.py +++ b/.github/scripts/generate-nix-options-docs.py @@ -1,80 +1,112 @@ #!/usr/bin/env python3 """ -Converts NixOS options JSON into clean, table-formatted Markdown. +Converts NixOS options JSON into clean Markdown documentation. """ import json import sys import re +SECTIONS = [ + { + "title": "NixOS", + "subtitle": "**System-level options via `programs.mango`.**", + }, + { + "title": "Home Manager", + "subtitle": "**Configure mangowm declaratively via `wayland.windowManager.mango`.**", + }, +] + +HEADER = ( + "---\n" + "title: Nix Module Options\n" + "description: NixOS and Home Manager configuration options for mangowm.\n" + "---\n\n" + "> **Note:** This document is automatically generated from the Nix module source code.\n\n" +) + def clean_description(desc: str) -> str: - """Removes Nix tags, fixes dangling periods, and formats blockquotes.""" + """Strips Nix inline markup tags, fixes dangling periods, and formats blockquotes.""" if not desc: return "*No description provided.*" - desc = re.sub(r'\{[a-zA-Z]+\}', '', desc).replace('\n.', '.') + # Strip Nix inline markup: {tag}`content` → `content`; bare tags → "" + desc = re.sub(r'\{(?:var|option|manpage|file|env|command|program)\}(`[^`]+`)', r'\1', desc) + desc = re.sub(r'\{(?:var|option|manpage|file|env|command|program)\}', '', desc) + # Remove period left on its own line after tag removal + desc = re.sub(r'\n\s*\.(\s|$)', r'.\1', desc) lines = desc.splitlines() cleaned = [] - in_note = False - + in_block = False + for line in lines: - if line.startswith("::: {.note"): - in_note = True - cleaned.append("> **Note:**\n>") + m = re.match(r':::\s*\{\.(\w+)\}', line) + if m: + block_type = m.group(1).capitalize() + in_block = True + cleaned.append(f"> **{block_type}:**\n>") elif line.startswith(":::"): - in_note = False + in_block = False else: - cleaned.append(f"> {line}" if in_note else line) + cleaned.append(f"> {line}" if in_block else line) return "\n".join(cleaned) -def format_default_value(default_data) -> str: - """Safely formats the default value, handling HTML escaping for tables.""" - if default_data is None: - return "*None*" +def format_value(val_data) -> str: + """Formats a value as inline code or a nix code block.""" + if val_data is None: + return None - val_text = default_data.get("text", "") if isinstance(default_data, dict) and default_data.get("_type") == "literalExpression" else str(default_data) - val_text = val_text.replace('|', '|') + if isinstance(val_data, dict) and val_data.get("_type") == "literalMD": + return val_data.get("text", "").strip() + elif isinstance(val_data, dict) and val_data.get("_type") == "literalExpression": + text = val_data.get("text", "").strip() + elif isinstance(val_data, bool): + text = "true" if val_data else "false" + elif val_data == {} or val_data == []: + text = "{ }" if val_data == {} else "[ ]" + else: + text = str(val_data).strip() - if '\n' in val_text: - safe_html = val_text.replace('<', '<').replace('>', '>').replace('\n', '<br>') - return f"<code>{safe_html}</code>" - - return f"`{val_text}`" + if '\n' in text: + return f"\n```nix\n{text}\n```" + return f"`{text}`" + +def write_section(out, data, title, subtitle): + out.write(f"## {title}\n\n{subtitle}\n\n") + for key, opt in sorted(data.items()): + if key.startswith("_module"): + continue + + desc = clean_description(opt.get("description", "")) + opt_type = str(opt.get("type", "unknown")) + default_val = format_value(opt.get("default")) + example_val = format_value(opt.get("example")) + + block = f"### `{key}`\n\n{desc}\n\n**Type:** `{opt_type}`\n\n" + if default_val is not None: + block += f"**Default:** {default_val}\n\n" + if example_val is not None: + block += f"**Example:** {example_val}\n\n" + block += "---\n\n" + out.write(block) def main(): if len(sys.argv) != 4: - sys.exit("Usage: format_docs.py <input.json> <output.md> <title>") + sys.exit("Usage: generate-nix-options-docs.py <nixos.json> <hm.json> <output.md>") - input_json, output_md, title = sys.argv[1:4] + nixos_json, hm_json, output_md = sys.argv[1:4] + inputs = [nixos_json, hm_json] - with open(input_json, 'r', encoding='utf-8') as f: - data = json.load(f) - - with open(output_md, 'a', encoding='utf-8') as out: - out.write(f"## {title}\n\n") - - for key, opt in sorted(data.items()): - if key.startswith("_module"): - continue - - desc = clean_description(opt.get("description", "")) - opt_type = str(opt.get("type", "unknown")).replace('|', '|') - default_val = format_default_value(opt.get("default")) - - markdown_block = ( - f"### `{key}`\n\n" - f"{desc}\n\n" - f"| Attribute | Value |\n" - f"| :--- | :--- |\n" - f"| **Type** | `{opt_type}` |\n" - f"| **Default** | {default_val} |\n\n" - f"---\n\n" - ) - out.write(markdown_block) - - print(f"Appended {title} to {output_md} successfully.") + with open(output_md, 'w', encoding='utf-8') as out: + out.write(HEADER) + for path, section in zip(inputs, SECTIONS): + with open(path, 'r', encoding='utf-8') as f: + data = json.load(f) + write_section(out, data, section["title"], section["subtitle"]) + print(f"Written {section['title']} section.") if __name__ == "__main__": main() diff --git a/.github/workflows/generate-nix-options-docs.yml b/.github/workflows/generate-nix-options-docs.yml index e5fd0df2..465146be 100644 --- a/.github/workflows/generate-nix-options-docs.yml +++ b/.github/workflows/generate-nix-options-docs.yml @@ -6,6 +6,7 @@ on: - 'nix/**-modules.nix' - 'nix/generate-options.nix' - 'flake.nix' + - '.github/scripts/generate-nix-options-docs.py' pull_request: paths: - 'nix/**-modules.nix' @@ -35,20 +36,10 @@ jobs: - name: Format to Markdown run: | - OUTPUT_FILE="docs/nix-options.md" - - cat << 'EOF' > $OUTPUT_FILE - --- - title: Nix Module Options - description: NixOS and Home Manager configuration options for mangowm. - --- - - > **Note:** This document is automatically generated from the Nix module source code. - - EOF - - python3 ./.github/scripts/generate-nix-options-docs.py result-nixos/share/doc/nixos/options.json $OUTPUT_FILE "NixOS Module Options" - python3 ./.github/scripts/generate-nix-options-docs.py result-hm/share/doc/nixos/options.json $OUTPUT_FILE "Home Manager Options" + python3 ./.github/scripts/generate-nix-options-docs.py \ + result-nixos/share/doc/nixos/options.json \ + result-hm/share/doc/nixos/options.json \ + docs/nix-options.md - name: Auto-commit changes uses: stefanzweifel/git-auto-commit-action@v5 diff --git a/nix/hm-modules.nix b/nix/hm-modules.nix index f00d9c68..f9a341a3 100644 --- a/nix/hm-modules.nix +++ b/nix/hm-modules.nix @@ -22,6 +22,7 @@ in enable = mkOption { type = types.bool; default = false; + description = "Whether to enable mangowm, a Wayland compositor based on dwl."; }; package = lib.mkOption { type = lib.types.package; From 406866d96a27b52149c8e0f48751e125580ebed8 Mon Sep 17 00:00:00 2001 From: Ruixi-rebirth <ruixirebirth@gmail.com> Date: Wed, 13 May 2026 05:11:57 +0800 Subject: [PATCH 4/5] docs(nix): add startup guide and clarify addLoginEntry - Replace 'Extra options' with greetd and getty autologin examples - Add bash/zsh and fish variants for getty autologin - Add link to Nix Module Options reference - Clarify addLoginEntry only has effect when a DM is configured --- docs/installation.md | 75 +++++++++++++++++++++++++++++++++++++++++-- nix/hm-modules.nix | 2 +- nix/nixos-modules.nix | 2 +- 3 files changed, 74 insertions(+), 5 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 6f3927a0..903d7cb9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -58,6 +58,7 @@ dnf install mangowm The package is hosted in the community-maintained **GURU** repository. 1. **Add the GURU repository** + ```bash emerge --ask --verbose eselect-repository eselect repository enable guru @@ -82,6 +83,7 @@ The package definition is described in the source repository. 1. **Add mango channel** Add to `$HOME/.config/guix/channels.scm`: + ```scheme (cons (channel (name 'mangowm) @@ -92,11 +94,13 @@ The package definition is described in the source repository. 2. **Install** After running `guix pull`, you can install mangowm: + ```bash guix install mangowm ``` Or add it to your system configuration using the mangowm module: + ```scheme (use-modules (mangowm)) @@ -115,6 +119,7 @@ The package definition is described in the source repository. The repository provides a Flake with a NixOS module. 1. **Add flake input** + ```nix # flake.nix { @@ -132,6 +137,7 @@ The repository provides a Flake with a NixOS module. 2. **Import the NixOS module** **Option A — Import in `configuration.nix`:** + ```nix # configuration.nix (or any other file that you import) {inputs, ...}: { @@ -145,6 +151,7 @@ The repository provides a Flake with a NixOS module. ``` **Option B — Import directly in flake:** + ```nix # flake.nix { @@ -165,6 +172,7 @@ The repository provides a Flake with a NixOS module. ``` 3. **Enable the module** + ```nix # configuration.nix (or any other file that you import) { @@ -172,9 +180,67 @@ The repository provides a Flake with a NixOS module. } ``` -4. **Extra options** - - `programs.mango.package` — the mango package to use, allows usage of custom mango drvs - - `programs.mango.addLoginEntry` (default: `true`) — adds login entry to the display manager +4. **Start mango on login** + + The following are common examples. Refer to the official NixOS documentation for full configuration options. + + **Option A — greetd:** Autologin on first start; login screen after logout. + + ```nix + services.greetd = { + enable = true; + settings = { + initial_session = { + command = "mango"; + user = "your-username"; # auto-login on first start, no password required + }; + default_session = { + command = "${pkgs.greetd.tuigreet}/bin/tuigreet --cmd mango"; + user = "greeter"; + }; + }; + }; + ``` + + **Option B — Display manager autologin:** Autologin via an existing display manager (e.g. SDDM, GDM). [`addLoginEntry`](/docs/nix-module#addloginentry) (default: `true`) automatically registers mango as a session. + + ```nix + services.displayManager = { + defaultSession = "mango"; # derived from mango.desktop filename + autoLogin = { + enable = true; + user = "your-username"; + }; + }; + ``` + + **Option C — getty autologin:** No login screen, boots directly into mango on TTY1. + + For bash/zsh: + + ```nix + services.getty.autologinUser = "your-username"; + + environment.loginShellInit = '' + [ "$(tty)" = /dev/tty1 ] && exec mango + ''; + ``` + + For fish: + + ```nix + services.getty.autologinUser = "your-username"; + + programs.fish.loginShellInit = '' + if test (tty) = /dev/tty1 + exec mango + end + ''; + ``` + +5. **All available options** + + See [Nix Module Options](/docs/nix-module) for the full list of NixOS and Home Manager options. --- @@ -195,6 +261,7 @@ pikman install mangowm If your distribution isn't listed above, or you want the latest unreleased changes, you can build mangowm from source. > **Info:** Ensure the following dependencies are installed before proceeding: +> > - `wayland` > - `wayland-protocols` > - `libinput` @@ -213,6 +280,7 @@ You will need to build `wlroots` and `scenefx` manually as well. 1. **Build wlroots** Clone and install the specific version required (check README for latest version). + ```bash git clone -b 0.19.3 https://gitlab.freedesktop.org/wlroots/wlroots.git cd wlroots @@ -222,6 +290,7 @@ You will need to build `wlroots` and `scenefx` manually as well. 2. **Build scenefx** This library handles the visual effects. + ```bash git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git cd scenefx diff --git a/nix/hm-modules.nix b/nix/hm-modules.nix index f9a341a3..eba05e2f 100644 --- a/nix/hm-modules.nix +++ b/nix/hm-modules.nix @@ -102,7 +102,7 @@ in description = '' Mango configuration written in Nix. Entries with the same key should be written as lists. Variables and colors names should be - quoted. See <https://mangowc.vercel.app/docs> for more examples. + quoted. See <https://mangowm.github.io/docs> for more examples. ::: {.note} This option uses a structured format that is converted to Mango's diff --git a/nix/nixos-modules.nix b/nix/nixos-modules.nix index 7295fffa..9144bbf1 100644 --- a/nix/nixos-modules.nix +++ b/nix/nixos-modules.nix @@ -12,7 +12,7 @@ in { addLoginEntry = lib.mkOption { type = lib.types.bool; default = true; - description = "Whether to add a login entry to the display manager for mango"; + description = "Whether to add a login entry to the display manager for mango. Only has effect if a display manager is configured (e.g. SDDM, GDM via `services.displayManager`)."; }; package = lib.mkOption { type = lib.types.package; From 0cea4a8a0d0a1b4345e882a861ef9e257de9fe38 Mon Sep 17 00:00:00 2001 From: Ruixi-rebirth <75824585+Ruixi-rebirth@users.noreply.github.com> Date: Tue, 12 May 2026 22:09:44 +0000 Subject: [PATCH 5/5] docs: auto-generate Nix module options --- docs/nix-options.md | 296 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 296 insertions(+) create mode 100644 docs/nix-options.md diff --git a/docs/nix-options.md b/docs/nix-options.md new file mode 100644 index 00000000..2a5d2038 --- /dev/null +++ b/docs/nix-options.md @@ -0,0 +1,296 @@ +--- +title: Nix Module Options +description: NixOS and Home Manager configuration options for mangowm. +--- + +> **Note:** This document is automatically generated from the Nix module source code. + +## NixOS + +**System-level options via `programs.mango`.** + +### `addLoginEntry` + +Whether to add a login entry to the display manager for mango. Only has effect if a display manager is configured (e.g. SDDM, GDM via `services.displayManager`). + +**Type:** `boolean` + +**Default:** `true` + +--- + +### `enable` + +Whether to enable mango, a wayland compositor based on dwl. + +**Type:** `boolean` + +**Default:** `false` + +**Example:** `true` + +--- + +### `package` + +The mango package to use + +**Type:** `package` + +**Default:** `<derivation mango-nightly>` + +--- + +## Home Manager + +**Configure mangowm declaratively via `wayland.windowManager.mango`.** + +### `autostart_sh` + +Shell script to run on mango startup. No shebang needed. + +When this option is set, the script will be written to +`~/.config/mango/autostart.sh` and an `exec-once` line +will be automatically added to the config to execute it. + +**Type:** `strings concatenated with "\n"` + +**Default:** `""` + +**Example:** +```nix +'' + waybar & + dunst & +'' +``` + +--- + +### `bottomPrefixes` + +List of prefixes for attributes that should appear at the bottom of the config file. +Attributes starting with these prefixes will be sorted to the end. + +**Type:** `list of string` + +**Default:** `[ ]` + +**Example:** +```nix +[ + "source" +] +``` + +--- + +### `enable` + +Whether to enable mangowm, a Wayland compositor based on dwl. + +**Type:** `boolean` + +**Default:** `false` + +--- + +### `extraConfig` + +Extra configuration lines to add to `~/.config/mango/config.conf`. +This is useful for advanced configurations that don't fit the structured +settings format, or for options that aren't yet supported by the module. + +**Type:** `strings concatenated with "\n"` + +**Default:** `""` + +**Example:** +```nix +'' + # Advanced config that doesn't fit structured format + special_option = 1 +'' +``` + +--- + +### `package` + +The mango package to use + +**Type:** `package` + +**Default:** `<derivation mango-nightly>` + +--- + +### `settings` + +Mango configuration written in Nix. Entries with the same key +should be written as lists. Variables and colors names should be +quoted. See <https://mangowm.github.io/docs> for more examples. + +> **Note:** +> +> This option uses a structured format that is converted to Mango's +> configuration syntax. Nested attributes are flattened with underscore separators. +> For example: `animation.duration_open = 400` becomes `animation_duration_open = 400` +> +> Keymodes (submaps) are supported via the special `keymode` attribute. Each keymode +> is a nested attribute set under `keymode` that contains its own bindings. + +**Type:** `Mango configuration value` + +**Default:** `{ }` + +**Example:** +```nix +{ + # Window effects + blur = 1; + blur_optimized = 1; + blur_params = { + radius = 5; + num_passes = 2; + }; + border_radius = 6; + focused_opacity = 1.0; + + # Animations - use underscores for multi-part keys + animations = 1; + animation_type_open = "slide"; + animation_type_close = "slide"; + animation_duration_open = 400; + animation_duration_close = 800; + + # Or use nested attrs (will be flattened with underscores) + animation_curve = { + open = "0.46,1.0,0.29,1"; + close = "0.08,0.92,0,1"; + }; + + # Use lists for duplicate keys like bind and tagrule + bind = [ + "SUPER,r,reload_config" + "Alt,space,spawn,rofi -show drun" + "Alt,Return,spawn,foot" + "ALT,R,setkeymode,resize" # Enter resize mode + ]; + + tagrule = [ + "id:1,layout_name:tile" + "id:2,layout_name:scroller" + ]; + + # Keymodes (submaps) for modal keybindings + keymode = { + resize = { + bind = [ + "NONE,Left,resizewin,-10,0" + "NONE,Escape,setkeymode,default" + ]; + }; + }; +} +``` + +--- + +### `systemd.enable` + +Whether to enable `mango-session.target` on +mango startup. This links to +`graphical-session.target`. +Some important environment variables will be imported to systemd +and dbus user environment before reaching the target, including +* `DISPLAY` +* `WAYLAND_DISPLAY` +* `XDG_CURRENT_DESKTOP` +* `XDG_SESSION_TYPE` +* `NIXOS_OZONE_WL` +You can extend this list using the `systemd.variables` option. + +**Type:** `boolean` + +**Default:** `true` + +**Example:** `false` + +--- + +### `systemd.extraCommands` + +Extra commands to run after D-Bus activation. + +**Type:** `list of string` + +**Default:** +```nix +[ + "systemctl --user reset-failed" + "systemctl --user start mango-session.target" +] +``` + +--- + +### `systemd.variables` + +Environment variables imported into the systemd and D-Bus user environment. + +**Type:** `list of string` + +**Default:** +```nix +[ + "DISPLAY" + "WAYLAND_DISPLAY" + "XDG_CURRENT_DESKTOP" + "XDG_SESSION_TYPE" + "NIXOS_OZONE_WL" + "XCURSOR_THEME" + "XCURSOR_SIZE" +] +``` + +**Example:** +```nix +[ + "--all" +] +``` + +--- + +### `systemd.xdgAutostart` + +Whether to enable autostart of applications using +`systemd-xdg-autostart-generator(8)`. + +**Type:** `boolean` + +**Default:** `false` + +**Example:** `true` + +--- + +### `topPrefixes` + +List of prefixes for attributes that should appear at the top of the config file. +Attributes starting with these prefixes will be sorted to the beginning. + +**Type:** `list of string` + +**Default:** `[ ]` + +**Example:** +```nix +[ + "source" +] +``` + +--- +