diff --git a/README.md b/README.md
index 9338584..798eb96 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,10 @@
# disko - Declarative disk partitioning
-![Project logo](./docs/logo.jpeg)
+
+
+
+[Documentation Index](./docs/INDEX.md)
NixOS is a Linux distribution where everything is described as code, with one exception: during installation, the disk partitioning and formatting are manual steps. **disko** aims to correct this sad 🤡 omission.
@@ -23,7 +26,6 @@ You can keep your configuration and re-use it for other installations, or for a
It can work with these in various configurations and orders, and supports recursive layouts.
-
## How to use disko
Disko doesn't require installation: it can be run directly from nix-community repository. The [Quickstart Guide](./docs/quickstart.md) documents how to run Disko in its simplest form when installing NixOS.
diff --git a/docs/INDEX.md b/docs/INDEX.md
new file mode 100644
index 0000000..5661b6a
--- /dev/null
+++ b/docs/INDEX.md
@@ -0,0 +1,13 @@
+# disko - Declarative disk partitioning
+
+
+
+## Table of Contents
+
+- [README](../README.md)
+- [Quickstart](./quickstart.md)
+- [System Requirements](./requirements.md)
+- [How to Guide](./HowTo.md)
+- [Support Matrix](./supportmatrix.md)
+- [Reference](./reference.md)
+- [Upgrade Guide](./upgrade-guide.md)
diff --git a/docs/quickstart.md b/docs/quickstart.md
index d2916f6..ac83a1a 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,10 +1,16 @@
-# Quickstart: disko
+# disko - Declarative disk partitioning
+
+
+
+[Documentation Index](./INDEX.md)
+
+## Quickstart Guide
This tutorial describes how to install NixOS on a single disk system using `disko`. You will also need to refer to the NixOS manual, which is available [here.](https://nixos.org/manual/nixos/stable/index.html#ex-config)
Please note that `disko` will reformat the entire disk and overwrite any existing partitions. Dual booting with other operating systems is not supported.
-## Step 1: Choose a Disk Configuration
+### Step 1: Choose a Disk Configuration
Configurations for the most common disk layouts are provided in the [examples directory](https://github.com/nix-community/disko/tree/master/example) of the `disko` repository. Decide which of these layouts best suits your requirements. If you're not sure which layout to pick, use the [hybrid](https://github.com/nix-community/disko/blob/master/example/hybrid.nix) configuration. This layout is compatible with both BIOS and EFI systems.
@@ -16,11 +22,11 @@ Once you've chosen your layout, you'll need to make a note of the URL to the raw
https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix
```
-## Step 2: Boot the installer
+### Step 2: Boot the installer
Download the NixOS ISO image from the NixOS [download page](https://nixos.org/download.html#nixos-iso), and create a bootable USB drive following the instructions in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb) of the NixOS manual. Boot the machine from this USB drive.
-## Step 3: Retrieve the disk name
+### Step 3: Retrieve the disk name
Identify the name of your system disk by using the ```lsblk``` command as follows:
@@ -37,7 +43,7 @@ nvme0n1 259:0 0 1,8T 0 disk
In this example, an empty NVME SSD with 2TB space is shown with the disk name "nvme0n1". Make a note of the disk name as you will need it later.
-## Step 4: Copy the disk configuration to your machine
+### Step 4: Copy the disk configuration to your machine
In Step 1, you chose a disk layout configuration from the [examples directory](https://github.com/nix-community/disko/tree/master/example), and made a note of its URL.
@@ -48,7 +54,7 @@ cd /tmp
$ curl https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix -o disko-config.nix
```
-## Step 5: Run disko to partition, format and mount your disks
+### Step 5: Run disko to partition, format and mount your disks
The following step will partition and format your disk, and mount it to `/mnt`. Replace `` with the name of your disk obtained in Step 1.
@@ -77,7 +83,7 @@ The output should look like this if your disk name is `nvme0n1`.
/dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro)
```
-## Step 6: Complete the NixOS installation.
+### Step 6: Complete the NixOS installation.
Your disks have now been formatted and mounted, and you are ready to complete the NixOS installation as described in the [NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation) - see the section headed "**Installing**", Steps 3 onwards. However, you will need to include the partitioning and formatting configurations that you copied into `/tmp/disko-config.nix` in your configuration, rather than allowing NixOS to generate information about your file systems. When you are configuring the system as per Step 4 of the manual, you should:
diff --git a/docs/requirements.md b/docs/requirements.md
new file mode 100644
index 0000000..9fffd93
--- /dev/null
+++ b/docs/requirements.md
@@ -0,0 +1,9 @@
+# disko - Declarative disk partitioning
+
+
+
+[Documentation Index](./INDEX.md)
+
+## System Requirements
+
+TODO: Populate this
diff --git a/docs/supportmatrix.md b/docs/supportmatrix.md
new file mode 100644
index 0000000..a3825d4
--- /dev/null
+++ b/docs/supportmatrix.md
@@ -0,0 +1,9 @@
+# disko - Declarative disk partitioning
+
+
+
+[Documentation Index](./INDEX.md)
+
+## Support Matrix
+
+TODO: Populate this