diff --git a/README.md b/README.md
index a502e4c26..faeba5bf8 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 If you have questions, check the documentation at [kubespray.io](https://kubespray.io) and join us on the [kubernetes slack](https://kubernetes.slack.com), channel **\#kubespray**.
 You can get your invite [here](http://slack.k8s.io/)
 
-- Can be deployed on **[AWS](docs/aws.md), GCE, [Azure](docs/azure.md), [OpenStack](docs/openstack.md), [vSphere](docs/vsphere.md), [Equinix Metal](docs/equinix-metal.md) (bare metal), Oracle Cloud Infrastructure (Experimental), or Baremetal**
+- Can be deployed on **[AWS](docs/cloud_providers/aws.md), GCE, [Azure](docs/cloud_providers/azure.md), [OpenStack](docs/cloud_providers/openstack.md), [vSphere](docs/cloud_providers/vsphere.md), [Equinix Metal](docs/cloud_providers/equinix-metal.md) (bare metal), Oracle Cloud Infrastructure (Experimental), or Baremetal**
 - **Highly available** cluster
 - **Composable** (Choice of the network plugin for instance)
 - Supports most popular **Linux distributions**
@@ -19,7 +19,7 @@ Below are several ways to use Kubespray to deploy a Kubernetes cluster.
 
 #### Usage
 
-Install Ansible according to [Ansible installation guide](/docs/ansible.md#installing-ansible)
+Install Ansible according to [Ansible installation guide](/docs/ansible/ansible.md#installing-ansible)
 then run the following steps:
 
 ```ShellSession
@@ -86,7 +86,7 @@ ansible-playbook -i /inventory/inventory.ini --private-key /root/.ssh/id_rsa clu
 
 #### Collection
 
-See [here](docs/ansible_collection.md) if you wish to use this repository as an Ansible collection
+See [here](docs/ansible/ansible_collection.md) if you wish to use this repository as an Ansible collection
 
 ### Vagrant
 
@@ -99,7 +99,7 @@ python -V && pip -V
 
 If this returns the version of the software, you're good to go. If not, download and install Python from here <https://www.python.org/downloads/source/>
 
-Install Ansible according to [Ansible installation guide](/docs/ansible.md#installing-ansible)
+Install Ansible according to [Ansible installation guide](/docs/ansible/ansible.md#installing-ansible)
 then run the following step:
 
 ```ShellSession
@@ -109,51 +109,51 @@ vagrant up
 ## Documents
 
 - [Requirements](#requirements)
-- [Kubespray vs ...](docs/comparisons.md)
-- [Getting started](docs/getting-started.md)
-- [Setting up your first cluster](docs/setting-up-your-first-cluster.md)
-- [Ansible inventory and tags](docs/ansible.md)
-- [Integration with existing ansible repo](docs/integration.md)
-- [Deployment data variables](docs/vars.md)
-- [DNS stack](docs/dns-stack.md)
-- [HA mode](docs/ha-mode.md)
+- [Kubespray vs ...](docs/getting_started/comparisons.md)
+- [Getting started](docs/getting_started/getting-started.md)
+- [Setting up your first cluster](docs/getting_started/setting-up-your-first-cluster.md)
+- [Ansible inventory and tags](docs/ansible/ansible.md)
+- [Integration with existing ansible repo](docs/operations/integration.md)
+- [Deployment data variables](docs/ansible/vars.md)
+- [DNS stack](docs/advanced/dns-stack.md)
+- [HA mode](docs/operations/ha-mode.md)
 - [Network plugins](#network-plugins)
-- [Vagrant install](docs/vagrant.md)
-- [Flatcar Container Linux bootstrap](docs/flatcar.md)
-- [Fedora CoreOS bootstrap](docs/fcos.md)
-- [openSUSE setup](docs/opensuse.md)
-- [Downloaded artifacts](docs/downloads.md)
-- [Cloud providers](docs/cloud.md)
-- [OpenStack](docs/openstack.md)
-- [AWS](docs/aws.md)
-- [Azure](docs/azure.md)
-- [vSphere](docs/vsphere.md)
-- [Equinix Metal](docs/equinix-metal.md)
-- [Large deployments](docs/large-deployments.md)
-- [Adding/replacing a node](docs/nodes.md)
-- [Upgrades basics](docs/upgrades.md)
-- [Air-Gap installation](docs/offline-environment.md)
-- [NTP](docs/ntp.md)
-- [Hardening](docs/hardening.md)
-- [Mirror](docs/mirror.md)
-- [Roadmap](docs/roadmap.md)
+- [Vagrant install](docs/developers/vagrant.md)
+- [Flatcar Container Linux bootstrap](docs/operating_systems/flatcar.md)
+- [Fedora CoreOS bootstrap](docs/operating_systems/fcos.md)
+- [openSUSE setup](docs/operating_systems/opensuse.md)
+- [Downloaded artifacts](docs/advanced/downloads.md)
+- [Cloud providers](docs/cloud_providers/cloud.md)
+- [OpenStack](docs/cloud_providers/openstack.md)
+- [AWS](docs/cloud_providers/aws.md)
+- [Azure](docs/cloud_providers/azure.md)
+- [vSphere](docs/cloud_providers/vsphere.md)
+- [Equinix Metal](docs/cloud_providers/equinix-metal.md)
+- [Large deployments](docs/operations/large-deployments.md)
+- [Adding/replacing a node](docs/operations/nodes.md)
+- [Upgrades basics](docs/operations/upgrades.md)
+- [Air-Gap installation](docs/operations/offline-environment.md)
+- [NTP](docs/advanced/ntp.md)
+- [Hardening](docs/operations/hardening.md)
+- [Mirror](docs/operations/mirror.md)
+- [Roadmap](docs/roadmap/roadmap.md)
 
 ## Supported Linux Distributions
 
 - **Flatcar Container Linux by Kinvolk**
 - **Debian** Bookworm, Bullseye, Buster
 - **Ubuntu** 20.04, 22.04
-- **CentOS/RHEL** 7, [8, 9](docs/centos.md#centos-8)
+- **CentOS/RHEL** 7, [8, 9](docs/operating_systems/centos.md#centos-8)
 - **Fedora** 37, 38
-- **Fedora CoreOS** (see [fcos Note](docs/fcos.md))
+- **Fedora CoreOS** (see [fcos Note](docs/operating_systems/fcos.md))
 - **openSUSE** Leap 15.x/Tumbleweed
-- **Oracle Linux** 7, [8, 9](docs/centos.md#centos-8)
-- **Alma Linux** [8, 9](docs/centos.md#centos-8)
-- **Rocky Linux** [8, 9](docs/centos.md#centos-8)
-- **Kylin Linux Advanced Server V10** (experimental: see [kylin linux notes](docs/kylinlinux.md))
-- **Amazon Linux 2** (experimental: see [amazon linux notes](docs/amazonlinux.md))
-- **UOS Linux** (experimental: see [uos linux notes](docs/uoslinux.md))
-- **openEuler** (experimental: see [openEuler notes](docs/openeuler.md))
+- **Oracle Linux** 7, [8, 9](docs/operating_systems/centos.md#centos-8)
+- **Alma Linux** [8, 9](docs/operating_systems/centos.md#centos-8)
+- **Rocky Linux** [8, 9](docs/operating_systems/centos.md#centos-8)
+- **Kylin Linux Advanced Server V10** (experimental: see [kylin linux notes](docs/operating_systems/kylinlinux.md))
+- **Amazon Linux 2** (experimental: see [amazon linux notes](docs/operating_systems/amazonlinux.md))
+- **UOS Linux** (experimental: see [uos linux notes](docs/operating_systems/uoslinux.md))
+- **openEuler** (experimental: see [openEuler notes](docs/operating_systems/openeuler.md))
 
 Note: Upstart/SysV init based OS types are not supported.
 
@@ -164,7 +164,7 @@ Note: Upstart/SysV init based OS types are not supported.
   - [etcd](https://github.com/etcd-io/etcd) v3.5.12
   - [docker](https://www.docker.com/) v24.0 (see [Note](#container-runtime-notes))
   - [containerd](https://containerd.io/) v1.7.16
-  - [cri-o](http://cri-o.io/) v1.29.1 (experimental: see [CRI-O Note](docs/cri-o.md). Only on fedora, ubuntu and centos based OS)
+  - [cri-o](http://cri-o.io/) v1.29.1 (experimental: see [CRI-O Note](docs/CRI/cri-o.md). Only on fedora, ubuntu and centos based OS)
 - Network Plugin
   - [cni-plugins](https://github.com/containernetworking/plugins) v1.2.0
   - [calico](https://github.com/projectcalico/calico) v3.27.3
@@ -204,7 +204,7 @@ Note: Upstart/SysV init based OS types are not supported.
 
 - **Minimum required version of Kubernetes is v1.27**
 - **Ansible v2.14+, Jinja 2.11+ and python-netaddr is installed on the machine that will run Ansible commands**
-- The target servers must have **access to the Internet** in order to pull docker images. Otherwise, additional configuration is required (See [Offline Environment](docs/offline-environment.md))
+- The target servers must have **access to the Internet** in order to pull docker images. Otherwise, additional configuration is required (See [Offline Environment](docs/operations/offline-environment.md))
 - The target servers are configured to allow **IPv4 forwarding**.
 - If using IPv6 for pods and services, the target servers are configured to allow **IPv6 forwarding**.
 - The **firewalls are not managed**, you'll need to implement your own rules the way you used to.
@@ -225,7 +225,7 @@ These limits are safeguarded by Kubespray. Actual requirements for your workload
 
 You can choose among ten network plugins. (default: `calico`, except Vagrant uses `flannel`)
 
-- [flannel](docs/flannel.md): gre/vxlan (layer 2) networking.
+- [flannel]CNI/flannel.md): gre/vxlan (layer 2) networking.
 
 - [Calico](https://docs.tigera.io/calico/latest/about/) is a networking and network policy provider. Calico supports a flexible set of networking options
     designed to give you the most efficient networking across a range of situations, including non-overlay
@@ -234,32 +234,32 @@ You can choose among ten network plugins. (default: `calico`, except Vagrant use
 
 - [cilium](http://docs.cilium.io/en/latest/): layer 3/4 networking (as well as layer 7 to protect and secure application protocols), supports dynamic insertion of BPF bytecode into the Linux kernel to implement security services, networking and visibility logic.
 
-- [weave](docs/weave.md): Weave is a lightweight container overlay network that doesn't require an external K/V database cluster.
+- [weave](docs/CNI/weave.md): Weave is a lightweight container overlay network that doesn't require an external K/V database cluster.
     (Please refer to `weave` [troubleshooting documentation](https://www.weave.works/docs/net/latest/troubleshooting/)).
 
-- [kube-ovn](docs/kube-ovn.md): Kube-OVN integrates the OVN-based Network Virtualization with Kubernetes. It offers an advanced Container Network Fabric for Enterprises.
+- [kube-ovn](docs/CNI/kube-ovn.md): Kube-OVN integrates the OVN-based Network Virtualization with Kubernetes. It offers an advanced Container Network Fabric for Enterprises.
 
-- [kube-router](docs/kube-router.md): Kube-router is a L3 CNI for Kubernetes networking aiming to provide operational
+- [kube-router](docs/CNI/kube-router.md): Kube-router is a L3 CNI for Kubernetes networking aiming to provide operational
     simplicity and high performance: it uses IPVS to provide Kube Services Proxy (if setup to replace kube-proxy),
     iptables for network policies, and BGP for ods L3 networking (with optionally BGP peering with out-of-cluster BGP peers).
     It can also optionally advertise routes to Kubernetes cluster Pods CIDRs, ClusterIPs, ExternalIPs and LoadBalancerIPs.
 
-- [macvlan](docs/macvlan.md): Macvlan is a Linux network driver. Pods have their own unique Mac and Ip address, connected directly the physical (layer 2) network.
+- [macvlan](docs/CNI/macvlan.md): Macvlan is a Linux network driver. Pods have their own unique Mac and Ip address, connected directly the physical (layer 2) network.
 
-- [multus](docs/multus.md): Multus is a meta CNI plugin that provides multiple network interface support to pods. For each interface Multus delegates CNI calls to secondary CNI plugins such as Calico, macvlan, etc.
+- [multus](docs/CNI/multus.md): Multus is a meta CNI plugin that provides multiple network interface support to pods. For each interface Multus delegates CNI calls to secondary CNI plugins such as Calico, macvlan, etc.
 
 - [custom_cni](roles/network-plugin/custom_cni/) : You can specify some manifests that will be applied to the clusters to bring you own CNI and use non-supported ones by Kubespray.
   See `tests/files/custom_cni/README.md` and `tests/files/custom_cni/values.yaml`for an example with a CNI provided by a Helm Chart.
 
 The network plugin to use is defined by the variable `kube_network_plugin`. There is also an
 option to leverage built-in cloud provider networking instead.
-See also [Network checker](docs/netcheck.md).
+See also [Network checker](docs/advanced/netcheck.md).
 
 ## Ingress Plugins
 
 - [nginx](https://kubernetes.github.io/ingress-nginx): the NGINX Ingress Controller.
 
-- [metallb](docs/metallb.md): the MetalLB bare-metal service LoadBalancer provider.
+- [metallb](docs/ingress/metallb.md): the MetalLB bare-metal service LoadBalancer provider.
 
 ## Community docs and resources
 
@@ -280,4 +280,4 @@ See also [Network checker](docs/netcheck.md).
 
 CI/end-to-end tests sponsored by: [CNCF](https://cncf.io), [Equinix Metal](https://metal.equinix.com/), [OVHcloud](https://www.ovhcloud.com/), [ELASTX](https://elastx.se/).
 
-See the [test matrix](docs/test_cases.md) for details.
+See the [test matrix](docs/developers/test_cases.md) for details.
diff --git a/contrib/azurerm/README.md b/contrib/azurerm/README.md
index f24a5ec23..8869ec091 100644
--- a/contrib/azurerm/README.md
+++ b/contrib/azurerm/README.md
@@ -49,7 +49,7 @@ If you need to delete all resources from a resource group, simply call:
 
 ## Installing Ansible and the dependencies
 
-Install Ansible according to [Ansible installation guide](/docs/ansible.md#installing-ansible)
+Install Ansible according to [Ansible installation guide](/docs/ansible/ansible.md#installing-ansible)
 
 ## Generating an inventory for kubespray
 
diff --git a/contrib/terraform/equinix/README.md b/contrib/terraform/equinix/README.md
index d1eb71f3f..f81e066a0 100644
--- a/contrib/terraform/equinix/README.md
+++ b/contrib/terraform/equinix/README.md
@@ -35,7 +35,7 @@ now six total etcd replicas.
 ## Requirements
 
 - [Install Terraform](https://www.terraform.io/intro/getting-started/install.html)
-- [Install Ansible dependencies](/docs/ansible.md#installing-ansible)
+- [Install Ansible dependencies](/docs/ansible/ansible.md#installing-ansible)
 - Account with Equinix Metal
 - An SSH key pair
 
diff --git a/contrib/terraform/openstack/README.md b/contrib/terraform/openstack/README.md
index 923aa3140..5e88849f5 100644
--- a/contrib/terraform/openstack/README.md
+++ b/contrib/terraform/openstack/README.md
@@ -619,7 +619,7 @@ Edit `inventory/$CLUSTER/group_vars/k8s_cluster/k8s_cluster.yml`:
 
 - Set variable **kube_network_plugin** to your desired networking plugin.
   - **flannel** works out-of-the-box
-  - **calico** requires [configuring OpenStack Neutron ports](/docs/openstack.md) to allow service and pod subnets
+  - **calico** requires [configuring OpenStack Neutron ports](/docs/cloud_providers/openstack.md) to allow service and pod subnets
 
 ```yml
 # Choose network plugin (calico, weave or flannel)
diff --git a/docs/calico.md b/docs/CNI/calico.md
similarity index 99%
rename from docs/calico.md
rename to docs/CNI/calico.md
index fb9ab06f8..8708f0bcc 100644
--- a/docs/calico.md
+++ b/docs/CNI/calico.md
@@ -382,7 +382,7 @@ To clean up any ipvs leftovers:
 
 Calico node, typha and kube-controllers need to be able to talk to the kubernetes API. Please reference the [Enabling eBPF Calico Docs](https://docs.projectcalico.org/maintenance/ebpf/enabling-bpf) for guidelines on how to do this.
 
-Kubespray sets up the `kubernetes-services-endpoint` configmap based on the contents of the `loadbalancer_apiserver` inventory variable documented in [HA Mode](/docs/ha-mode.md).
+Kubespray sets up the `kubernetes-services-endpoint` configmap based on the contents of the `loadbalancer_apiserver` inventory variable documented in [HA Mode](/docs/operations/ha-mode.md).
 
 If no external loadbalancer is used, Calico eBPF can also use the localhost loadbalancer option. We are able to do so only if you use the same port for the localhost apiserver loadbalancer and the kube-apiserver. In this case Calico Automatic Host Endpoints need to be enabled to allow services like `coredns` and `metrics-server` to communicate with the kubernetes host endpoint. See [this blog post](https://www.projectcalico.org/securing-kubernetes-nodes-with-calico-automatic-host-endpoints/) on enabling automatic host endpoints.
 
diff --git a/docs/cilium.md b/docs/CNI/cilium.md
similarity index 99%
rename from docs/cilium.md
rename to docs/CNI/cilium.md
index afc808c64..a773dbc90 100644
--- a/docs/cilium.md
+++ b/docs/CNI/cilium.md
@@ -99,7 +99,7 @@ cilium_operator_extra_volume_mounts:
 ## Choose Cilium version
 
 ```yml
-cilium_version: v1.15.4
+cilium_version: v1.12.1
 ```
 
 ## Add variable to config
diff --git a/docs/cni.md b/docs/CNI/cni.md
similarity index 100%
rename from docs/cni.md
rename to docs/CNI/cni.md
diff --git a/docs/flannel.md b/docs/CNI/flannel.md
similarity index 100%
rename from docs/flannel.md
rename to docs/CNI/flannel.md
diff --git a/docs/kube-ovn.md b/docs/CNI/kube-ovn.md
similarity index 100%
rename from docs/kube-ovn.md
rename to docs/CNI/kube-ovn.md
diff --git a/docs/kube-router.md b/docs/CNI/kube-router.md
similarity index 100%
rename from docs/kube-router.md
rename to docs/CNI/kube-router.md
diff --git a/docs/macvlan.md b/docs/CNI/macvlan.md
similarity index 100%
rename from docs/macvlan.md
rename to docs/CNI/macvlan.md
diff --git a/docs/multus.md b/docs/CNI/multus.md
similarity index 100%
rename from docs/multus.md
rename to docs/CNI/multus.md
diff --git a/docs/weave.md b/docs/CNI/weave.md
similarity index 100%
rename from docs/weave.md
rename to docs/CNI/weave.md
diff --git a/docs/containerd.md b/docs/CRI/containerd.md
similarity index 100%
rename from docs/containerd.md
rename to docs/CRI/containerd.md
diff --git a/docs/cri-o.md b/docs/CRI/cri-o.md
similarity index 100%
rename from docs/cri-o.md
rename to docs/CRI/cri-o.md
diff --git a/docs/docker.md b/docs/CRI/docker.md
similarity index 100%
rename from docs/docker.md
rename to docs/CRI/docker.md
diff --git a/docs/gvisor.md b/docs/CRI/gvisor.md
similarity index 100%
rename from docs/gvisor.md
rename to docs/CRI/gvisor.md
diff --git a/docs/kata-containers.md b/docs/CRI/kata-containers.md
similarity index 100%
rename from docs/kata-containers.md
rename to docs/CRI/kata-containers.md
diff --git a/docs/aws-ebs-csi.md b/docs/CSI/aws-ebs-csi.md
similarity index 100%
rename from docs/aws-ebs-csi.md
rename to docs/CSI/aws-ebs-csi.md
diff --git a/docs/azure-csi.md b/docs/CSI/azure-csi.md
similarity index 100%
rename from docs/azure-csi.md
rename to docs/CSI/azure-csi.md
diff --git a/docs/cinder-csi.md b/docs/CSI/cinder-csi.md
similarity index 100%
rename from docs/cinder-csi.md
rename to docs/CSI/cinder-csi.md
diff --git a/docs/gcp-pd-csi.md b/docs/CSI/gcp-pd-csi.md
similarity index 100%
rename from docs/gcp-pd-csi.md
rename to docs/CSI/gcp-pd-csi.md
diff --git a/docs/vsphere-csi.md b/docs/CSI/vsphere-csi.md
similarity index 100%
rename from docs/vsphere-csi.md
rename to docs/CSI/vsphere-csi.md
diff --git a/docs/arch.md b/docs/advanced/arch.md
similarity index 100%
rename from docs/arch.md
rename to docs/advanced/arch.md
diff --git a/docs/cert_manager.md b/docs/advanced/cert_manager.md
similarity index 100%
rename from docs/cert_manager.md
rename to docs/advanced/cert_manager.md
diff --git a/docs/dns-stack.md b/docs/advanced/dns-stack.md
similarity index 100%
rename from docs/dns-stack.md
rename to docs/advanced/dns-stack.md
diff --git a/docs/downloads.md b/docs/advanced/downloads.md
similarity index 100%
rename from docs/downloads.md
rename to docs/advanced/downloads.md
diff --git a/docs/gcp-lb.md b/docs/advanced/gcp-lb.md
similarity index 100%
rename from docs/gcp-lb.md
rename to docs/advanced/gcp-lb.md
diff --git a/docs/kubernetes-reliability.md b/docs/advanced/kubernetes-reliability.md
similarity index 100%
rename from docs/kubernetes-reliability.md
rename to docs/advanced/kubernetes-reliability.md
diff --git a/docs/mitogen.md b/docs/advanced/mitogen.md
similarity index 100%
rename from docs/mitogen.md
rename to docs/advanced/mitogen.md
diff --git a/docs/netcheck.md b/docs/advanced/netcheck.md
similarity index 100%
rename from docs/netcheck.md
rename to docs/advanced/netcheck.md
diff --git a/docs/ntp.md b/docs/advanced/ntp.md
similarity index 100%
rename from docs/ntp.md
rename to docs/advanced/ntp.md
diff --git a/docs/proxy.md b/docs/advanced/proxy.md
similarity index 100%
rename from docs/proxy.md
rename to docs/advanced/proxy.md
diff --git a/docs/kubernetes-apps/registry.md b/docs/advanced/registry.md
similarity index 100%
rename from docs/kubernetes-apps/registry.md
rename to docs/advanced/registry.md
diff --git a/docs/ansible.md b/docs/ansible/ansible.md
similarity index 99%
rename from docs/ansible.md
rename to docs/ansible/ansible.md
index 3fbf57ea5..43769e0d9 100644
--- a/docs/ansible.md
+++ b/docs/ansible/ansible.md
@@ -59,7 +59,7 @@ not _kube_node_.
 
 There are also two special groups:
 
-* **calico_rr** : explained for [advanced Calico networking cases](/docs/calico.md)
+* **calico_rr** : explained for [advanced Calico networking cases](/docs/CNI/calico.md)
 * **bastion** : configure a bastion host if your nodes are not directly reachable
 
 Below is a complete inventory example:
@@ -285,7 +285,7 @@ For more information about Ansible and bastion hosts, read
 
 ## Mitogen
 
-Mitogen support is deprecated, please see [mitogen related docs](/docs/mitogen.md) for usage and reasons for deprecation.
+Mitogen support is deprecated, please see [mitogen related docs](/docs/advanced/mitogen.md) for usage and reasons for deprecation.
 
 ## Beyond ansible 2.9
 
diff --git a/docs/ansible_collection.md b/docs/ansible/ansible_collection.md
similarity index 100%
rename from docs/ansible_collection.md
rename to docs/ansible/ansible_collection.md
diff --git a/docs/vars.md b/docs/ansible/vars.md
similarity index 99%
rename from docs/vars.md
rename to docs/ansible/vars.md
index 0e83b1831..c2cdaa099 100644
--- a/docs/vars.md
+++ b/docs/ansible/vars.md
@@ -46,11 +46,11 @@ Some variables of note include:
 * *loadbalancer_apiserver* - If defined, all hosts will connect to this
   address instead of localhost for kube_control_planes and kube_control_plane[0] for
   kube_nodes. See more details in the
-  [HA guide](/docs/ha-mode.md).
+  [HA guide](/docs/operations/ha-mode.md).
 * *loadbalancer_apiserver_localhost* - makes all hosts to connect to
   the apiserver internally load balanced endpoint. Mutual exclusive to the
   `loadbalancer_apiserver`. See more details in the
-  [HA guide](/docs/ha-mode.md).
+  [HA guide](/docs/operations/ha-mode.md).
 
 ## Cluster variables
 
diff --git a/docs/aws.md b/docs/cloud_providers/aws.md
similarity index 100%
rename from docs/aws.md
rename to docs/cloud_providers/aws.md
diff --git a/docs/azure.md b/docs/cloud_providers/azure.md
similarity index 100%
rename from docs/azure.md
rename to docs/cloud_providers/azure.md
diff --git a/docs/cloud.md b/docs/cloud_providers/cloud.md
similarity index 100%
rename from docs/cloud.md
rename to docs/cloud_providers/cloud.md
diff --git a/docs/equinix-metal.md b/docs/cloud_providers/equinix-metal.md
similarity index 98%
rename from docs/equinix-metal.md
rename to docs/cloud_providers/equinix-metal.md
index ccdabaed2..3616dc9ef 100644
--- a/docs/equinix-metal.md
+++ b/docs/cloud_providers/equinix-metal.md
@@ -54,7 +54,7 @@ cd kubespray
 
 ## Install Ansible
 
-Install Ansible according to [Ansible installation guide](/docs/ansible.md#installing-ansible)
+Install Ansible according to [Ansible installation guide](/docs/ansible/ansible.md#installing-ansible)
 
 ## Cluster Definition
 
diff --git a/docs/openstack.md b/docs/cloud_providers/openstack.md
similarity index 100%
rename from docs/openstack.md
rename to docs/cloud_providers/openstack.md
diff --git a/docs/vsphere.md b/docs/cloud_providers/vsphere.md
similarity index 99%
rename from docs/vsphere.md
rename to docs/cloud_providers/vsphere.md
index a75a25d9a..72a2c1dba 100644
--- a/docs/vsphere.md
+++ b/docs/cloud_providers/vsphere.md
@@ -54,7 +54,7 @@ external_vsphere_kubernetes_cluster_id: "kubernetes-cluster-id"
 vsphere_csi_enabled: true
 ```
 
-For a more fine-grained CSI setup, refer to the [vsphere-csi](/docs/vsphere-csi.md) documentation.
+For a more fine-grained CSI setup, refer to the [vsphere-csi](/docs/CSI/vsphere-csi.md) documentation.
 
 ### Deployment
 
diff --git a/docs/ci-setup.md b/docs/developers/ci-setup.md
similarity index 100%
rename from docs/ci-setup.md
rename to docs/developers/ci-setup.md
diff --git a/docs/ci.md b/docs/developers/ci.md
similarity index 100%
rename from docs/ci.md
rename to docs/developers/ci.md
diff --git a/docs/test_cases.md b/docs/developers/test_cases.md
similarity index 94%
rename from docs/test_cases.md
rename to docs/developers/test_cases.md
index b26d3aa50..1937e7ebe 100644
--- a/docs/test_cases.md
+++ b/docs/developers/test_cases.md
@@ -25,7 +25,7 @@ Note, the canal network plugin deploys flannel as well plus calico policy contro
 
 ## Test cases
 
-The [CI Matrix](/docs/ci.md) displays OS, Network Plugin and Container Manager tested.
+The [CI Matrix](/docs/developers/ci.md) displays OS, Network Plugin and Container Manager tested.
 
 All tests are breakdown into 3 "stages" ("Stage" means a build step of the build pipeline) as follows:
 
diff --git a/docs/vagrant.md b/docs/developers/vagrant.md
similarity index 99%
rename from docs/vagrant.md
rename to docs/developers/vagrant.md
index 9e12351af..824b3953b 100644
--- a/docs/vagrant.md
+++ b/docs/developers/vagrant.md
@@ -52,7 +52,7 @@ speed, the variable 'download_run_once' is set. This will make kubespray
 download all files and containers just once and then redistributes them to
 the other nodes and as a bonus, also cache all downloads locally and re-use
 them on the next provisioning run. For more information on download settings
-see [download documentation](/docs/downloads.md).
+see [download documentation](/docs/advanced/downloads.md).
 
 ## Example use of Vagrant
 
diff --git a/docs/kubernetes-apps/cephfs_provisioner.md b/docs/external_storage_provisioners/cephfs_provisioner.md
similarity index 100%
rename from docs/kubernetes-apps/cephfs_provisioner.md
rename to docs/external_storage_provisioners/cephfs_provisioner.md
diff --git a/docs/kubernetes-apps/local_volume_provisioner.md b/docs/external_storage_provisioners/local_volume_provisioner.md
similarity index 100%
rename from docs/kubernetes-apps/local_volume_provisioner.md
rename to docs/external_storage_provisioners/local_volume_provisioner.md
diff --git a/docs/kubernetes-apps/rbd_provisioner.md b/docs/external_storage_provisioners/rbd_provisioner.md
similarity index 100%
rename from docs/kubernetes-apps/rbd_provisioner.md
rename to docs/external_storage_provisioners/rbd_provisioner.md
diff --git a/docs/kubernetes-apps/scheduler_plugins.md b/docs/external_storage_provisioners/scheduler_plugins.md
similarity index 100%
rename from docs/kubernetes-apps/scheduler_plugins.md
rename to docs/external_storage_provisioners/scheduler_plugins.md
diff --git a/docs/comparisons.md b/docs/getting_started/comparisons.md
similarity index 100%
rename from docs/comparisons.md
rename to docs/getting_started/comparisons.md
diff --git a/docs/getting-started.md b/docs/getting_started/getting-started.md
similarity index 96%
rename from docs/getting-started.md
rename to docs/getting_started/getting-started.md
index 32660d1d3..1cfb26f1c 100644
--- a/docs/getting-started.md
+++ b/docs/getting_started/getting-started.md
@@ -36,7 +36,7 @@ ansible-playbook -i inventory/mycluster/hosts.yml cluster.yml -b -v \
   --private-key=~/.ssh/private_key
 ```
 
-See more details in the [ansible guide](/docs/ansible.md).
+See more details in the [ansible guide](/docs/ansible/ansible.md).
 
 ### Adding nodes
 
@@ -81,7 +81,7 @@ kube-apiserver via port 8080. A kubeconfig file is not necessary in this case,
 because kubectl will use <http://localhost:8080> to connect. The kubeconfig files
 generated will point to localhost (on kube_control_planes) and kube_node hosts will
 connect either to a localhost nginx proxy or to a loadbalancer if configured.
-More details on this process are in the [HA guide](/docs/ha-mode.md).
+More details on this process are in the [HA guide](/docs/operations/ha-mode.md).
 
 Kubespray permits connecting to the cluster remotely on any IP of any
 kube_control_plane host on port 6443 by default. However, this requires
@@ -140,5 +140,5 @@ If desired, copy admin.conf to ~/.kube/config.
 
 ## Setting up your first cluster
 
-[Setting up your first cluster](/docs/setting-up-your-first-cluster.md) is an
+[Setting up your first cluster](/docs/getting_started/setting-up-your-first-cluster.md) is an
  applied step-by-step guide for setting up your first cluster with Kubespray.
diff --git a/docs/setting-up-your-first-cluster.md b/docs/getting_started/setting-up-your-first-cluster.md
similarity index 100%
rename from docs/setting-up-your-first-cluster.md
rename to docs/getting_started/setting-up-your-first-cluster.md
diff --git a/docs/ingress_controller/alb_ingress_controller.md b/docs/ingress/alb_ingress_controller.md
similarity index 100%
rename from docs/ingress_controller/alb_ingress_controller.md
rename to docs/ingress/alb_ingress_controller.md
diff --git a/docs/ingress_controller/ingress_nginx.md b/docs/ingress/ingress_nginx.md
similarity index 100%
rename from docs/ingress_controller/ingress_nginx.md
rename to docs/ingress/ingress_nginx.md
diff --git a/docs/kube-vip.md b/docs/ingress/kube-vip.md
similarity index 100%
rename from docs/kube-vip.md
rename to docs/ingress/kube-vip.md
diff --git a/docs/metallb.md b/docs/ingress/metallb.md
similarity index 100%
rename from docs/metallb.md
rename to docs/ingress/metallb.md
diff --git a/docs/amazonlinux.md b/docs/operating_systems/amazonlinux.md
similarity index 100%
rename from docs/amazonlinux.md
rename to docs/operating_systems/amazonlinux.md
diff --git a/docs/bootstrap-os.md b/docs/operating_systems/bootstrap-os.md
similarity index 100%
rename from docs/bootstrap-os.md
rename to docs/operating_systems/bootstrap-os.md
diff --git a/docs/centos.md b/docs/operating_systems/centos.md
similarity index 100%
rename from docs/centos.md
rename to docs/operating_systems/centos.md
diff --git a/docs/fcos.md b/docs/operating_systems/fcos.md
similarity index 100%
rename from docs/fcos.md
rename to docs/operating_systems/fcos.md
diff --git a/docs/flatcar.md b/docs/operating_systems/flatcar.md
similarity index 100%
rename from docs/flatcar.md
rename to docs/operating_systems/flatcar.md
diff --git a/docs/kylinlinux.md b/docs/operating_systems/kylinlinux.md
similarity index 100%
rename from docs/kylinlinux.md
rename to docs/operating_systems/kylinlinux.md
diff --git a/docs/openeuler.md b/docs/operating_systems/openeuler.md
similarity index 100%
rename from docs/openeuler.md
rename to docs/operating_systems/openeuler.md
diff --git a/docs/opensuse.md b/docs/operating_systems/opensuse.md
similarity index 100%
rename from docs/opensuse.md
rename to docs/operating_systems/opensuse.md
diff --git a/docs/rhel.md b/docs/operating_systems/rhel.md
similarity index 100%
rename from docs/rhel.md
rename to docs/operating_systems/rhel.md
diff --git a/docs/uoslinux.md b/docs/operating_systems/uoslinux.md
similarity index 100%
rename from docs/uoslinux.md
rename to docs/operating_systems/uoslinux.md
diff --git a/docs/cgroups.md b/docs/operations/cgroups.md
similarity index 100%
rename from docs/cgroups.md
rename to docs/operations/cgroups.md
diff --git a/docs/encrypting-secret-data-at-rest.md b/docs/operations/encrypting-secret-data-at-rest.md
similarity index 100%
rename from docs/encrypting-secret-data-at-rest.md
rename to docs/operations/encrypting-secret-data-at-rest.md
diff --git a/docs/etcd.md b/docs/operations/etcd.md
similarity index 100%
rename from docs/etcd.md
rename to docs/operations/etcd.md
diff --git a/docs/ha-mode.md b/docs/operations/ha-mode.md
similarity index 100%
rename from docs/ha-mode.md
rename to docs/operations/ha-mode.md
diff --git a/docs/hardening.md b/docs/operations/hardening.md
similarity index 100%
rename from docs/hardening.md
rename to docs/operations/hardening.md
diff --git a/docs/integration.md b/docs/operations/integration.md
similarity index 100%
rename from docs/integration.md
rename to docs/operations/integration.md
diff --git a/docs/large-deployments.md b/docs/operations/large-deployments.md
similarity index 90%
rename from docs/large-deployments.md
rename to docs/operations/large-deployments.md
index 4666d073e..3182c27b8 100644
--- a/docs/large-deployments.md
+++ b/docs/operations/large-deployments.md
@@ -9,7 +9,7 @@ For a large scaled deployments, consider the following configuration changes:
 * Override containers' `foo_image_repo` vars to point to intranet registry.
 
 * Override the ``download_run_once: true`` and/or ``download_localhost: true``.
-  See [Downloading binaries and containers](/docs/downloads.md) for details.
+  See [Downloading binaries and containers](/docs/advanced/downloads.md) for details.
 
 * Adjust the `retry_stagger` global var as appropriate. It should provide sane
   load on a delegate (the first K8s control plane node) then retrying failed
@@ -32,7 +32,7 @@ For a large scaled deployments, consider the following configuration changes:
   ``kube_controller_node_monitor_period``,
   ``kube_apiserver_pod_eviction_not_ready_timeout_seconds`` &
   ``kube_apiserver_pod_eviction_unreachable_timeout_seconds`` for better Kubernetes reliability.
-  Check out [Kubernetes Reliability](/docs/kubernetes-reliability.md)
+  Check out [Kubernetes Reliability](/docs/advanced/kubernetes-reliability.md)
 
 * Tune network prefix sizes. Those are ``kube_network_node_prefix``,
   ``kube_service_addresses`` and ``kube_pods_subnet``.
@@ -41,7 +41,7 @@ For a large scaled deployments, consider the following configuration changes:
   from host/network interruption much quicker with calico_rr.
 
 * Check out the
-  [Inventory](/docs/getting-started.md#building-your-own-inventory)
+  [Inventory](/docs/getting_started/getting-started.md#building-your-own-inventory)
   section of the Getting started guide for tips on creating a large scale
   Ansible inventory.
 
diff --git a/docs/mirror.md b/docs/operations/mirror.md
similarity index 100%
rename from docs/mirror.md
rename to docs/operations/mirror.md
diff --git a/docs/nodes.md b/docs/operations/nodes.md
similarity index 100%
rename from docs/nodes.md
rename to docs/operations/nodes.md
diff --git a/docs/offline-environment.md b/docs/operations/offline-environment.md
similarity index 100%
rename from docs/offline-environment.md
rename to docs/operations/offline-environment.md
diff --git a/docs/port-requirements.md b/docs/operations/port-requirements.md
similarity index 100%
rename from docs/port-requirements.md
rename to docs/operations/port-requirements.md
diff --git a/docs/recover-control-plane.md b/docs/operations/recover-control-plane.md
similarity index 100%
rename from docs/recover-control-plane.md
rename to docs/operations/recover-control-plane.md
diff --git a/docs/upgrades.md b/docs/operations/upgrades.md
similarity index 100%
rename from docs/upgrades.md
rename to docs/operations/upgrades.md
diff --git a/docs/roadmap.md b/docs/roadmap/roadmap.md
similarity index 100%
rename from docs/roadmap.md
rename to docs/roadmap/roadmap.md