it should get the TOC from the global _toc.yaml...

admin-guide/deployment.rst

@@ -14,12 +14,5 @@ a command line client is available.
 When PXE boot is not an option, e.g. in restricted networks, it is possible to
 start iPXE from a USB stick or other media.
 
-.. toctree::
-   :maxdepth: 2
-
-   deployment/ipxe
-   deployment/kickstart
-   deployment/partitioning
-   deployment/sample
-   deployment/infrastructure
-   deployment/workflow
+```{tableofcontents}
+```

admin-guide/deployment/ipxe.md

@@ -1,8 +1,6 @@
-PXE-booting with iPXE
-=====================
+# PXE-booting with iPXE
 
-UEFI
-----
+## UEFI
 
 iPXE supports UEFI and so do we. This requires the ``ipxe.efi`` boot image.
 
@@ -10,7 +8,6 @@ Instructions how to copy the necessary grub files to the tftp server:
 https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/installation_guide/chap-installation-server-setup#sect-network-boot-setup-uefi
 (alternatively one can also copy the files from the /boot/efi/EFI/redhat/ directory of an installed system)
 
-
 ```
 [root@ tmp]# cd /tmp
 [root@ tmp]# curl -OL http://repos.psi.ch/rhel9/iso/rhel-baseos-9.1-x86_64-dvd/BaseOS/Packages/shim-x64-15.6-1.el9.x86_64.rpm
@@ -56,23 +53,22 @@ drwxr-xr-x. 4 root root      32 Mar  1 16:16 ..
 ```
 
 
-Process
--------
+## Process
 
 When a system PXE boots, the DHCP server will boot either pxelinux in legacy
 mode or grub on UEFI. It is still possible to load ipxe from either of these.
 With the right option, the boot process is pointed to ``sysdb.psi.ch`` and one
 of the following boot images:
 
-- ``ipxe.efi`` for systems using UEFI
-- ``ipxe.lkrn`` for all other systems
+- `ipxe.efi` for systems using UEFI
+- `ipxe.lkrn` for all other systems
 
 The system downloads the image and executes it.
 
 The image contains a small iPXE script, which makes iPXE retrieve its actual
-configuration from a web service running (usually) on ``sysdb.psi.ch``.
+configuration from a web service running (usually) on `sysdb.psi.ch`.
 Specifically, it queries the URL
-``https://sysdb.psi.ch/ipxe/v1/config?mac=<MAC>``, where ``<MAC>`` is the MAC
+`https://sysdb.psi.ch/ipxe/v1/config?mac=<MAC>`, where `<MAC>` is the MAC
 address of the interface used by iPXE.
 
 The web service on ``sysdb.psi.ch`` will generate the iPXE configuration on the
@@ -81,42 +77,40 @@ which distribution it is supposed to use. The menu offers other options as well,
 e.g. an interactive iPXE shell and a memory test.
 
 
-Sequence Diagram of the UEFI Boot Process
---------------------------------------------------
-.. image:: _static/uefi_boot.png
+## Sequence Diagram of the UEFI Boot Process
+![UEFI boot process](_static/uefi_boot.png)
 
 
-Sequence Diagram of the BIOS (Legacy) Boot Process
---------------------------------------------------
-.. image:: _static/legacy_boot.png
+## Sequence Diagram of the BIOS (Legacy) Boot Process
+![Legacy boot process](_static/legacy_boot.png)
 
 
-Building the iPXE boot image
-----------------------------
+## Building the iPXE boot image
 
 The steps for building an iPXE image are
 
-1. Clone ``git@git.psi.ch:linux-infra/ipxe-build.git``
+1. Clone `git@git.psi.ch:linux-infra/ipxe-build.git`
 2. Change into the new directory
-3. Run the ``refresh-ipxe.sh`` script. This will check out the iPXE source code
-   mirror from ``git.psi.ch``.
-4. Run the ``build.sh`` script. This will use the named configurations in the
-   ``ipxe-build`` repository to compile two iPXE images: ``src/bin/ipxe.lkrn``
-   (legacy boot) and ``src/bin-x86_64-efi/ipxe.efi`` (UEFI).
+3. Run the `refresh-ipxe.sh` script. This will check out the iPXE source code
+   mirror from `git.psi.ch`.
+4. Run the `build.sh` script. This will use the named configurations in the
+   `ipxe-build` repository to compile two iPXE images: `src/bin/ipxe.lkrn`
+   (legacy boot) and `src/bin-x86_64-efi/ipxe.efi` (UEFI).
 
 
 As described above, we use an iPXE boot image with an embedded script looking
-roughly like the following::
+roughly like the following
+```
+#!ipxe
 
-  #!ipxe
-  
-  dhcp && goto dhcp_succeeded
-  
-  shell
-  #prompt for network info
-  
-  :dhcp_succeeded
-  
-  chain http://sysdb.psi.ch/ipxe/v1/config?mac=${netX/mac}
+dhcp && goto dhcp_succeeded
+
+shell
+#prompt for network info
+
+:dhcp_succeeded
+
+chain http://sysdb.psi.ch/ipxe/v1/config?mac=${netX/mac}
+```