diff --git a/_toc.yml b/_toc.yml
index 4a4f1af..474b245 100644
--- a/_toc.yml
+++ b/_toc.yml
@@ -52,6 +52,8 @@ chapters:
       - file: admin-guide/selinux
       - file: admin-guide/kerberos
       - file: admin-guide/software
+        sections:
+          - file: admin-guide/software/updates
       - file: admin-guide/mgmt-tools
       - file: admin-guide/operations
       - file: admin-guide/third-party
diff --git a/admin-guide/software.rst b/admin-guide/software.md
similarity index 74%
rename from admin-guide/software.rst
rename to admin-guide/software.md
index bde6011..8cbb5ef 100644
--- a/admin-guide/software.rst
+++ b/admin-guide/software.md
@@ -1,23 +1,17 @@
-Software and Licenses
-=====================
+# Software and Licenses
+
+```{tableofcontents}
+```
 
 
-.. toctree::
-   :maxdepth: 1
-
-   software/updates
-
-
-Licenses
-========
+## Licenses
 
 Our Red Hat Enterprise Linux subscriptions are provided by ETHZ, other licenses
 are usually managed by Roland Blättler.
 
-The RHEL repositories can be accessed on the `ETHZ Satellite server
-<https://id-sat-prd-02.ethz.ch>`_. It is only accessible from within PSI and a
+The RHEL repositories can be accessed on the [ETHZ Satellite server](https://id-sat-prd-02.ethz.ch). It is only accessible from within PSI and a
 special account is needed, which can be requested at
-https://cd-portal.sp.ethz.ch/_layouts/15/start.aspx#/SitePages/Home.aspx.
+<https://cd-portal.sp.ethz.ch/_layouts/15/start.aspx#/SitePages/Home.aspx>.
 
 One thing to keep in mind is that several groups at PSI use the Satellite server
 directly, so not all PSI hosts known to the Satellite belong to the central
@@ -30,35 +24,33 @@ track subscription usage. When we started using the ETHZ subscriptions in 2016
 we provided an estimate of 2000 systems max.
 
 
-Distribution and deployment
----------------------------
+## Distribution and deployment
 
 All software is distributed as RPMs with the following exceptions:
 
 - some software is provided via AFS/NFS instead
 - configuration files and scripts that can be considered configuration, e.g. the
-  files in ``/etc/cron.daily``
+  files in `/etc/cron.daily`
 - server applications can be deployed by cloning a Git repository (e.g. sysdb)
 
 There are a number of advantages to deploying software as RPM:
 
 - automatic installation/protection of dependencies
-- inventory of installed software (``rpm -qa`` etc) including version
+- inventory of installed software (`rpm -qa` etc) including version
   information
-- integrity checking (``rpm -q --verify``)
-- ownership tracking (``rpm -qf``, ``yum provides``)
+- integrity checking (`rpm -q --verify`)
+- ownership tracking (`rpm -qf`, `yum provides`)
 - no network dependency, which is useful for laptops and increases reliability
   on other systems
 
 
-Repositories
-------------
+## Repositories
 
 We maintain an internal mirror for every repository that we use, or at least a
-local repository containing the specific packages. We never point ``yum.conf``
+local repository containing the specific packages. We never point `yum.conf`
 (or any other package manager) to an external repository directly.
 
-The repository server is ``repos.psi.ch``.
+The repository server is `repos.psi.ch`.
 
 Currently we maintain the following repositories:
 
@@ -82,10 +74,9 @@ definitions, the second one the list of repositories to mirror.
 
 
 
-Packaging
----------
+## Packaging
 
 All packaging information for in-house packages must be tracked in Git. The
 repositories containing packaging information should be in the
-`linux-packages <https://git.psi.ch/groups/linux-packages>`_ group on the
+[linux-packages](https://git.psi.ch/groups/linux-packages) group on the
 Gitlab server.