From 5992a2282193d0d9ef35a63610cd2ee4353dcc2d Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Mon, 21 Oct 2024 18:02:37 +0100
Subject: [PATCH] docs: introduce a dedicated homepage

Based of the README for now, with a small additional "welcome to the
docs" section.

Perhaps in future, we could re-use the README.md verbatim? Perhaps with
some additional post-processing.

I think we'd want to dramatically reduce its size first though.

By having a dedicated homepage outside of `user-guide`, this fixes #1625
---
 docs/mdbook/SUMMARY.md     |  2 ++
 docs/mdbook/index.md       | 36 ++++++++++++++++++++++++++++++++++++
 docs/user-guide/install.md |  4 ++--
 3 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 docs/mdbook/index.md

diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md
index 67fbff889..4dc6b76d7 100644
--- a/docs/mdbook/SUMMARY.md
+++ b/docs/mdbook/SUMMARY.md
@@ -1,5 +1,7 @@
 # Structure for nixvim docs
 
+- [Home](./index.md)
+
 # User guide
 
 - [Installation](./user-guide/install.md)
diff --git a/docs/mdbook/index.md b/docs/mdbook/index.md
new file mode 100644
index 000000000..458477009
--- /dev/null
+++ b/docs/mdbook/index.md
@@ -0,0 +1,36 @@
+# NixVim - A Neovim configuration system for nix
+
+## What is it?
+NixVim is a [Neovim](https://neovim.io) distribution built around
+[Nix](https://nixos.org) modules. It is distributed as a Nix flake, and
+configured through Nix, all while leaving room for your plugins and your vimrc.
+
+## What does it look like?
+Here is a simple configuration that uses catppuccin as the colorscheme and uses the
+lualine plugin:
+
+```nix
+{
+  programs.nixvim = {
+    enable = true;
+
+    colorschemes.catppuccin.enable = true;
+    plugins.lualine.enable = true;
+  };
+}
+```
+
+When we do this, lualine will be set up to a sensible default, and will use
+catppuccin as the colorscheme, no extra configuration required!
+
+Check out [this list of real world nixvim configs](./user-guide/config-examples.md)!
+
+## Welcome to the docs!
+
+Over to the left, you'll find the sidebar. There you'll see several "User guides" (including an [FAQ](./user-guide/faq.md)]), along with pages for various "options".
+
+While you can search our main docs using the <i class="fa fa-search"></i> icon, if you're looking for a specific option you may find the dedicated [Nixvim Option Search](./search/index.html) (at the bottom of the sidebar) has more relevant results.
+
+> [!TIP]
+> Any page with a ❱ icon next to it has one-or-more _sub-pages_.
+
diff --git a/docs/user-guide/install.md b/docs/user-guide/install.md
index c96b41a09..db099b08d 100644
--- a/docs/user-guide/install.md
+++ b/docs/user-guide/install.md
@@ -70,7 +70,7 @@ options as `programs.nixvim.<path>.<to>.<option> = <value>`.
 When you use nixvim as a module, an additional module argument is passed on allowing you to peek through the configuration with `hmConfig`, `nixosConfig`, and `darwinConfig` for home-manager, NixOS, and nix-darwin respectively.
 This is useful is you use nixvim both as part of an environment and as standalone.
 
-If using the home-manager module, see [Home Manager Usage](./modules/hm.md) for more information.
+If using the home-manager module, see [Home Manager Usage](../modules/hm.md) for more information.
 
 ### Standalone usage
 
@@ -88,4 +88,4 @@ The nixvim derivation can then be used like any other package!
 
 For an example, see the [nixvim standalone flake template](https://github.com/nix-community/nixvim/blob/main/templates/simple/flake.nix).
 
-For more information see [Standalone Usage](./modules/standalone.md).
+For more information see [Standalone Usage](../modules/standalone.md).