From 750412743384b0f96886e75affae143f916b1c57 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Leon=20Schwarz=C3=A4ugl?=
 <leon.schwarzaeugl@imba.oeaw.ac.at>
Date: Tue, 6 Jan 2026 11:18:45 +0100
Subject: [PATCH] docs: improve docs

---
 SwarselSystems.org | 999 ++++++++++++++++++++++++---------------------
 1 file changed, 542 insertions(+), 457 deletions(-)

diff --git a/SwarselSystems.org b/SwarselSystems.org
index 022583a..9b8b8f8 100644
--- a/SwarselSystems.org
+++ b/SwarselSystems.org
@@ -9,33 +9,31 @@
 #+macro: revision-date (eval (format-time-string "%F %T %z"))
 #+macro: count-words (eval (count-words (point-min) (point-max)))
 #+macro: count-lines (eval (count-lines (point-min) (point-max)))
+#+macro: NOTE (eval "This file has {{{count-words}}} words spanning {{{count-lines}}} lines and was last revised on {{{revision-date}}}.")
 
-*This file has {{{count-words}}} words spanning {{{count-lines}}} lines and was last revised on {{{revision-date}}}.*
+*{{{NOTE(If you can see this, you might want to switch to [[https://swarsel.github.io/.dotfiles/][the hmtl version of this document]] in order to have working links and other QoL functions while reading this file.)}}}*
 
-In order to have working links and macros when viewing this file online, you might want to switch to the [[https://swarsel.github.io/.dotfiles/][html version]].
 * Introduction (no code)
 :PROPERTIES:
 :CUSTOM_ID: h:a86fe971-f169-4052-aacf-15e0f267c6cd
 :END:
 
-This literate configuration file holds the entirety of all configuration files for both NixOS as well as home-manager across all machines that I currently use. It also holds an extensive Emacs configuration.
-
-I used to have two separate files (=Emacs.org= and =Nixos.org=) because the NixOS setting for installing Emacs packages used to break if it found UTF-8 characters in =.el= files but not in =.org= files. Hence I used to pass =Emacs.org= to that function rather than =init.el=. This seems to be fixed now however and I was finally able to consolidate both files into one.
+This literate configuration file holds the entirety of all configuration for both NixOS PCs and servers as well as home-manager only systems across all machines that I currently use. It also holds an extensive Emacs configuration. I use this project to manage my entire home + cloud infrastructure
 
 This configuration is part of a NixOS system that is (nearly) fully declarative and can be found here:
 
-- [[https:github.com/Swarsel/.dotfiles][~SwarselSystems~ on github.com]]
+- [[https://github.com/Swarsel/.dotfiles][Swarsel/.dotfiles on GitHub]]
 
-This literate configuration lets me explain my choices to my future self as well as you, the reader. I go to great lengths to explain the choices for all configuration steps that I take in order for me to pay due diligence in crafting my setup, and not simply copying big chunks of other peoples code. Also, the literate configuration approach is very convenient to me as I only need to keep of (ideally) a single file to manage all of my configuration. I hope that this documentation will make it easier for beginners to get into Emacs and NixOS as I know it can be a struggle in the beginning.
+The literate configuration approach lets me explain my choices to my future self as well as you, the reader. I go to great lengths to explain the choices for all design steps that I take in order for me to pay due diligence in crafting my setup, and not simply copying big chunks of other peoples code. Also, this is very convenient to me as I only need to keep of (ideally) a single file to manage all of my configuration. I hope that this documentation will make it easier for beginners to get into NixOS (and, to some extent, Emacs) as I know it can be a struggle in the beginning.
 
 ** How to use this document
 :PROPERTIES:
 :CUSTOM_ID: h:6f4b190c-fe69-47a3-9df2-ee429bd9b48b
 :END:
 
-When I started out with nix, it was a painful time. For a beginner, the available resources tend to be too detailed or assume too much prior knowledge. Also, it is a (sad) fact that using nix requires the user to understand it pretty well before most things start to make sense.
+When I started out with nix, it was a painful time. For a beginner, the available resources tend to be too detailed or assume too much prior knowledge. Also, it seems that using nix requires the user to understand it pretty well before many things start to make sense.
 
-That is the reason why I keep this configuration as a literate one: so that I am able to explain how everything works. In the start, it was my goal to keep this repo simple, so that it would be easy to understand when seen by a beginner. However, over time I have implemented more and more complicated solutions. Still, I try to keep the prosaic descriptions sufficient.
+That is the reason why I keep this configuration as a literate one: so that I am able to explain how everything works as best as I can. In the start, it was my goal to keep this project simple, so that it would be easy to understand when seen by a beginner. However, over time I have implemented more and more complicated solutions. Still, I try to keep the prosaic descriptions sufficient.
 
 For a beginner, I recommend to read this file like a book, from start to finish. I will try to explain concepts whenever they first come up, and will regularly link to [[#h:8ea35dcc-ef94-4c10-9112-8be8efd6f424][Appendix C: Explanations to nix functions and operators]] when more context is needed. For the first few times that I am using a new function, I will place such a link again. However, to keep the writing of this file manageable, I will generally only do this no more than three times.
 
@@ -166,449 +164,491 @@ window.addEventListener('load', addDarkmodeWidget);
 I also add this javascript to add header pinning functionality to the site, using the same trick as above:
 
 #+begin_src elisp :noweb yes :exports both :results html
-  "
-   <script>
-       (function() {
-           function ready(fn) {
-               if (document.readyState === 'loading') {
-                   document.addEventListener('DOMContentLoaded', fn);
-               } else {
-                   fn();
-               }
-           }
-
-           ready(function initPinned() {
-               const STORAGE_KEY = 'org-pinned-items-v2';
-
-               let pinnedPanel = document.getElementById('pinned-panel');
-               if (!pinnedPanel) {
-                   pinnedPanel = document.createElement('aside');
-                   pinnedPanel.id = 'pinned-panel';
-                   pinnedPanel.innerHTML = `
-               <div id='pinned-panel-header'>
-                 <h2>Pinned</h2>
-                 <button id='toggle-pinned-btn' type='button' title='Hide pinned panel'>✕</button>
-               </div>
-               <button id='clear-all-pins-btn' type='button'>Clear All</button>
-               <ul id='pinned-list'></ul>
-             `;
-                   document.body.appendChild(pinnedPanel);
-               }
-
-               let showBtn = document.getElementById('show-pinned-btn');
-               if (!showBtn) {
-                   showBtn = document.createElement('button');
-                   showBtn.id = 'show-pinned-btn';
-                   showBtn.type = 'button';
-                   showBtn.textContent = 'Pinned';
-                   document.body.appendChild(showBtn);
-               }
-
-               const content      = document.getElementById('content');
-               const pinnedList   = document.getElementById('pinned-list');
-               const toggleBtn    = document.getElementById('toggle-pinned-btn');
-               const clearAllBtn  = document.getElementById('clear-all-pins-btn');
-               const toc          = document.getElementById('table-of-contents');
-               const body         = document.body;
-
-               if (!content || !pinnedList || !toggleBtn || !clearAllBtn || !toc) return;
-               function injectSearch() {
-                   // Check if already injected
-                   if (document.getElementById('toc-search-input')) return;
-
-                   const searchContainer = document.createElement('div');
-                   searchContainer.id = 'toc-search-container';
-
-                   const searchInput = document.createElement('input');
-                   searchInput.id = 'toc-search-input';
-                   searchInput.type = 'text';
-                   searchInput.placeholder = 'Search TOC...';
-                   searchInput.autocomplete = 'off';
-
-                   const clearBtn = document.createElement('button');
-                   clearBtn.id = 'toc-search-clear';
-                   clearBtn.type = 'button';
-                   clearBtn.textContent = 'Clear';
-
-                   searchContainer.appendChild(searchInput);
-                   searchContainer.appendChild(clearBtn);
-
-                   toc.insertBefore(searchContainer, toc.firstChild);
-
-                   function filterTOC(term) {
-                       const allLinks = toc.querySelectorAll('a');
-
-                       allLinks.forEach(link => {
-                           const li = link.closest('li');
-                           if (!li) return;
-
-                           const text = link.textContent.toLowerCase();
-                           const matches = text.includes(term);
-
-                           if (matches) {
-                               li.classList.remove('hidden-by-search');
-                               let parent = li.parentElement;
-                               while (parent && parent !== toc) {
-                                   if (parent.tagName === 'UL') {
-                                       parent.style.display = '';
-                                   }
-                                   if (parent.tagName === 'LI') {
-                                       parent.classList.remove('hidden-by-search');
-                                   }
-                                   parent = parent.parentElement;
-                               }
-                           } else {
-                               li.classList.add('hidden-by-search');
-                           }
-                       });
-
-                       if (term === '') {
-                           const allLis = toc.querySelectorAll('li');
-                           allLis.forEach(li => li.classList.remove('hidden-by-search'));
-                       }
-                   }
-
-                   searchInput.addEventListener('input', function(e) {
-                       const term = e.target.value.toLowerCase();
-                       filterTOC(term);
-                   });
-
-                   clearBtn.addEventListener('click', function() {
-                       searchInput.value = '';
-                       filterTOC('');
-                       searchInput.focus();
-                   });
-               }
-               injectSearch();
-               function addHeadingLinks() {
-                   const headers = content.querySelectorAll('h1, h2, h3, h4, h5, h6');
-                   headers.forEach(header => {
-                       const id = header.getAttribute('id');
-                       if (!id) return;
-
-                       if (header.querySelector('.heading-link')) return;
-
-                       const link = document.createElement('a');
-                       link.className = 'heading-link';
-                       link.href = '#' + id;
-                       link.textContent = '#';
-                       link.title = 'Copy link to this heading';
-
-                       const pinBtn = header.querySelector('.toc-pin-btn');
-                       if (pinBtn) {
-                           header.insertBefore(link, pinBtn);
-                       } else {
-                           header.appendChild(link);
-                       }
-
-                       link.addEventListener('click', function(e) {
-                           e.preventDefault();
-                           const url = window.location.origin + window.location.pathname + '#' + id;
-
-                           if (navigator.clipboard && navigator.clipboard.writeText) {
-                               navigator.clipboard.writeText(url).then(() => {
-                                   const originalText = link.textContent;
-                                   link.textContent = '✓';
-                                   setTimeout(() => {
-                                       link.textContent = originalText;
-                                   }, 1000);
-                               }).catch(err => {
-                                   console.warn('Failed to copy to clipboard', err);
-                                   window.location.hash = id;
-                               });
-                           } else {
-                               window.location.hash = id;
-                           }
-                       });
-                   });
-               }
-               addHeadingLinks();
-
-               let mobileTocBtn = document.getElementById('mobile-toc-toggle');
-               if (!mobileTocBtn) {
-                   mobileTocBtn = document.createElement('button');
-                   mobileTocBtn.id = 'mobile-toc-toggle';
-                   mobileTocBtn.type = 'button';
-                   mobileTocBtn.textContent = 'TOC';
-                   document.body.appendChild(mobileTocBtn);
-               }
-
-               let mobilePinnedBtn = document.getElementById('mobile-pinned-toggle');
-               if (!mobilePinnedBtn) {
-                   mobilePinnedBtn = document.createElement('button');
-                   mobilePinnedBtn.id = 'mobile-pinned-toggle';
-                   mobilePinnedBtn.type = 'button';
-                   mobilePinnedBtn.textContent = 'Pinned';
-                   document.body.appendChild(mobilePinnedBtn);
-               }
-
-               function anyMobilePanelOpen() {
-                   return toc.classList.contains('mobile-visible') ||
-                       pinnedPanel.classList.contains('mobile-visible');
-               }
-
-               function updateBodyMobilePanelState() {
-                   if (anyMobilePanelOpen()) body.classList.add('mobile-panel-open');
-                   else body.classList.remove('mobile-panel-open');
-               }
-
-               document.addEventListener('click', function(e) {
-                   if (window.innerWidth > 1000) return;
-
-                   if (!anyMobilePanelOpen()) return;
-
-                   const clickedInsideToc = toc.contains(e.target);
-                   const clickedInsidePinned = pinnedPanel.contains(e.target);
-                   const clickedTocBtn = mobileTocBtn.contains(e.target);
-                   const clickedPinnedBtn = mobilePinnedBtn.contains(e.target);
-
-                   const clickedInteractive =
-                         e.target.tagName === 'A' ||
-                         e.target.tagName === 'BUTTON' ||
-                         e.target.tagName === 'INPUT' ||
-                         e.target.tagName === 'TEXTAREA' ||
-                         e.target.closest('a') ||
-                         e.target.closest('button');
-
-                   if (!clickedInsideToc && !clickedInsidePinned && !clickedTocBtn && !clickedPinnedBtn && !clickedInteractive) {
-                       toc.classList.remove('mobile-visible');
-                       pinnedPanel.classList.remove('mobile-visible');
-                       updateBodyMobilePanelState();
-                   }
-               });
-
-               mobileTocBtn.addEventListener('click', function() {
-                   const isOpen = toc.classList.toggle('mobile-visible');
-                   if (isOpen) {
-                       pinnedPanel.classList.remove('mobile-visible');
-                   }
-                   updateBodyMobilePanelState();
-               });
-
-               mobilePinnedBtn.addEventListener('click', function() {
-                   const isOpen = pinnedPanel.classList.toggle('mobile-visible');
-                   if (isOpen) {
-                       toc.classList.remove('mobile-visible');
-                   }
-                   updateBodyMobilePanelState();
-               });
-
-               const pinnedItems = new Map();
-               let initiallyPinnedHrefs = new Set();
-
-               function loadFromStorage() {
-                   try {
-                       const raw = window.localStorage && localStorage.getItem(STORAGE_KEY);
-                       if (!raw) return;
-                       const arr = JSON.parse(raw);
-                       if (!Array.isArray(arr)) return;
-                       initiallyPinnedHrefs = new Set(arr);
-                   } catch (e) {
-                       console.warn('Pinned: failed to load from localStorage', e);
-                   }
-               }
-
-               function saveToStorage() {
-                   try {
-                       if (!window.localStorage) return;
-                       const arr = [];
-                       pinnedItems.forEach((entry, href) => {
-                           if (entry.li) arr.push(href);
-                       });
-                       localStorage.setItem(STORAGE_KEY, JSON.stringify(arr));
-                   } catch (e) {
-                       console.warn('Pinned: failed to save to localStorage', e);
-                   }
-               }
-
-               function sortPinnedList() {
-                   const items = Array.from(pinnedList.children).map(li => {
-                       const link = li.querySelector('a');
-                       return {
-                           li: li,
-                           text: link ? link.textContent.trim().toLowerCase() : ''
-                       };
-                   });
-                   items.sort((a, b) => a.text.localeCompare(b.text));
-                   items.forEach(item => pinnedList.appendChild(item.li));
-               }
-
-               function hidePinnedPanel() {
-                   pinnedPanel.classList.add('hidden');
-                   content.classList.add('pinned-hidden');
-                   showBtn.classList.add('visible');
-               }
-
-               function showPinnedPanel() {
-                   pinnedPanel.classList.remove('hidden');
-                   content.classList.remove('pinned-hidden');
-                   showBtn.classList.remove('visible');
-               }
-
-               toggleBtn.addEventListener('click', hidePinnedPanel);
-               showBtn.addEventListener('click', showPinnedPanel);
-
-               clearAllBtn.addEventListener('click', function() {
-                   if (pinnedItems.size === 0) return;
-
-                   const confirmed = confirm('Are you sure you want to clear all pinned items?');
-                   if (!confirmed) return;
-
-                   pinnedItems.forEach((entry, href) => {
-                       if (entry.li && entry.li.parentElement) {
-                           entry.li.parentElement.removeChild(entry.li);
-                       }
-                       entry.li = null;
-                       entry.btns.forEach(b => b.textContent = '[pin]');
-                   });
-
-                   saveToStorage();
-               });
-
-               function attachPinBehavior(pinBtn, href, text) {
-                   if (!href) return;
-
-                   if (!pinnedItems.has(href)) {
-                       pinnedItems.set(href, { li: null, btns: new Set(), text: text });
-                   }
-                   const entry = pinnedItems.get(href);
-                   entry.btns.add(pinBtn);
-
-                   pinBtn.textContent = entry.li ? '[unpin]' : '[pin]';
-
-                   pinBtn.addEventListener('click', function(e) {
-                       e.preventDefault();
-                       e.stopPropagation();
-                       const current = pinnedItems.get(href);
-                       if (!current) return;
-
-                       if (current.li) {
-                           if (current.li.parentElement) {
-                               current.li.parentElement.removeChild(current.li);
-                           }
-                           current.li = null;
-                           current.btns.forEach(b => b.textContent = '[pin]');
-                           saveToStorage();
-                       } else {
-                           const li = document.createElement('li');
-
-                           const a = document.createElement('a');
-                           a.href = href;
-                           a.textContent = current.text;
-
-                           const removeBtn = document.createElement('button');
-                           removeBtn.className = 'pin-remove';
-                           removeBtn.type = 'button';
-                           removeBtn.textContent = '✕';
-                           removeBtn.addEventListener('click', () => {
-                               const cur = pinnedItems.get(href);
-                               if (!cur) return;
-                               if (cur.li && cur.li.parentElement) {
-                                   cur.li.parentElement.removeChild(cur.li);
-                               }
-                               cur.li = null;
-                               cur.btns.forEach(b => b.textContent = '[pin]');
-                               saveToStorage();
-                           });
-
-                           li.appendChild(a);
-                           li.appendChild(removeBtn);
-                           pinnedList.appendChild(li);
-
-                           current.li = li;
-                           current.btns.forEach(b => b.textContent = '[unpin]');
-
-                           sortPinnedList();
-                           saveToStorage();
-                       }
-                   });
-               }
-
-               loadFromStorage();
-
-               const tocLinks = document.querySelectorAll('#text-table-of-contents a');
-               tocLinks.forEach(link => {
-                   if (link.parentElement && link.parentElement.classList.contains('toc-entry')) {
-                       return;
-                   }
-                   const li = link.closest('li');
-                   if (!li) return;
-
-                   const wrapper = document.createElement('span');
-                   wrapper.className = 'toc-entry';
-                   li.insertBefore(wrapper, link);
-                   wrapper.appendChild(link);
-
-                   const pinBtn = document.createElement('button');
-                   pinBtn.className = 'toc-pin-btn';
-                   pinBtn.type = 'button';
-                   pinBtn.textContent = '[pin]';
-                   wrapper.appendChild(pinBtn);
-
-                   const href = link.getAttribute('href');
-                   const text = link.textContent.trim();
-                   attachPinBehavior(pinBtn, href, text);
-               });
-
-               const headers = content.querySelectorAll('h2, h3, h4, h5, h6');
-               headers.forEach(header => {
-                   const id = header.getAttribute('id');
-                   if (!id) return;
-                   if (header.querySelector('.toc-pin-btn')) return;
-
-                   const href = '#' + id;
-                   const text = header.textContent.trim();
-
-                   const pinBtn = document.createElement('button');
-                   pinBtn.className = 'toc-pin-btn';
-                   pinBtn.type = 'button';
-                   pinBtn.textContent = '[pin]';
-                   pinBtn.style.marginLeft = '0.8rem';
-                   pinBtn.style.fontSize  = '0.75em';
-
-                   header.appendChild(pinBtn);
-                   attachPinBehavior(pinBtn, href, text);
-               });
-
-               initiallyPinnedHrefs.forEach(href => {
-                   const entry = pinnedItems.get(href);
-                   if (!entry) return;
-
-                   const li = document.createElement('li');
-
-                   const a = document.createElement('a');
-                   a.href = href;
-                   a.textContent = entry.text;
-
-                   const removeBtn = document.createElement('button');
-                   removeBtn.className = 'pin-remove';
-                   removeBtn.type = 'button';
-                   removeBtn.textContent = '✕';
-                   removeBtn.addEventListener('click', () => {
-                       const cur = pinnedItems.get(href);
-                       if (!cur) return;
-                       if (cur.li && cur.li.parentElement) {
-                           cur.li.parentElement.removeChild(cur.li);
-                       }
-                       cur.li = null;
-                       cur.btns.forEach(b => b.textContent = '[pin]');
-                       saveToStorage();
-                   });
-
-                   li.appendChild(a);
-                   li.appendChild(removeBtn);
-                   pinnedList.appendChild(li);
-
-                   entry.li = li;
-                   entry.btns.forEach(b => b.textContent = '[unpin]');
-               });
-
-               sortPinnedList();
-               saveToStorage();
-           });
-       })();
-   </script>
-   "
+    "
+     <script>
+         (function() {
+             function ready(fn) {
+                 if (document.readyState === 'loading') {
+                     document.addEventListener('DOMContentLoaded', fn);
+                 } else {
+                     fn();
+                 }
+             }
+
+             ready(function initPinned() {
+                 const STORAGE_KEY = 'org-pinned-items-v2';
+
+                 let pinnedPanel = document.getElementById('pinned-panel');
+                 if (!pinnedPanel) {
+                     pinnedPanel = document.createElement('aside');
+                     pinnedPanel.id = 'pinned-panel';
+                     pinnedPanel.innerHTML = `
+                 <div id='pinned-panel-header'>
+                   <h2>Pinned</h2>
+                   <button id='toggle-pinned-btn' type='button' title='Hide pinned panel'>✕</button>
+                 </div>
+                 <button id='clear-all-pins-btn' type='button'>Clear All</button>
+                 <ul id='pinned-list'></ul>
+               `;
+                     document.body.appendChild(pinnedPanel);
+                 }
+
+                 let showBtn = document.getElementById('show-pinned-btn');
+                 if (!showBtn) {
+                     showBtn = document.createElement('button');
+                     showBtn.id = 'show-pinned-btn';
+                     showBtn.type = 'button';
+                     showBtn.textContent = 'Pinned';
+                     document.body.appendChild(showBtn);
+                 }
+
+                 const content      = document.getElementById('content');
+                 const pinnedList   = document.getElementById('pinned-list');
+                 const toggleBtn    = document.getElementById('toggle-pinned-btn');
+                 const clearAllBtn  = document.getElementById('clear-all-pins-btn');
+                 const toc          = document.getElementById('table-of-contents');
+                 const body         = document.body;
+
+                 if (!content || !pinnedList || !toggleBtn || !clearAllBtn || !toc) return;
+                 function injectSearch() {
+                     // Check if already injected
+                     if (document.getElementById('toc-search-input')) return;
+
+                     const searchContainer = document.createElement('div');
+                     searchContainer.id = 'toc-search-container';
+
+                     const searchInput = document.createElement('input');
+                     searchInput.id = 'toc-search-input';
+                     searchInput.type = 'text';
+                     searchInput.placeholder = 'Search TOC...';
+                     searchInput.autocomplete = 'off';
+
+                     const clearBtn = document.createElement('button');
+                     clearBtn.id = 'toc-search-clear';
+                     clearBtn.type = 'button';
+                     clearBtn.textContent = 'Clear';
+
+                     searchContainer.appendChild(searchInput);
+                     searchContainer.appendChild(clearBtn);
+
+                     toc.insertBefore(searchContainer, toc.firstChild);
+
+                     function filterTOC(term) {
+                         const allLinks = toc.querySelectorAll('a');
+
+                         allLinks.forEach(link => {
+                             const li = link.closest('li');
+                             if (!li) return;
+
+                             const text = link.textContent.toLowerCase();
+                             const matches = text.includes(term);
+
+                             if (matches) {
+                                 li.classList.remove('hidden-by-search');
+                                 let parent = li.parentElement;
+                                 while (parent && parent !== toc) {
+                                     if (parent.tagName === 'UL') {
+                                         parent.style.display = '';
+                                     }
+                                     if (parent.tagName === 'LI') {
+                                         parent.classList.remove('hidden-by-search');
+                                     }
+                                     parent = parent.parentElement;
+                                 }
+                             } else {
+                                 li.classList.add('hidden-by-search');
+                             }
+                         });
+
+                         if (term === '') {
+                             const allLis = toc.querySelectorAll('li');
+                             allLis.forEach(li => li.classList.remove('hidden-by-search'));
+                         }
+                     }
+
+                     searchInput.addEventListener('input', function(e) {
+                         const term = e.target.value.toLowerCase();
+                         filterTOC(term);
+                     });
+
+                     clearBtn.addEventListener('click', function() {
+                         searchInput.value = '';
+                         filterTOC('');
+                         searchInput.focus();
+                     });
+                 }
+                 injectSearch();
+                 function addHeadingLinks() {
+                     const headers = content.querySelectorAll('h1, h2, h3, h4, h5, h6, h7, h8, h9');
+                     headers.forEach(header => {
+                         const id = header.getAttribute('id');
+                         if (!id) return;
+
+                         if (header.querySelector('.heading-link')) return;
+
+                         const link = document.createElement('a');
+                         link.className = 'heading-link';
+                         link.href = '#' + id;
+                         link.textContent = '#';
+                         link.title = 'Copy link to this heading';
+
+                         const pinBtn = header.querySelector('.toc-pin-btn');
+                         if (pinBtn) {
+                             header.insertBefore(link, pinBtn);
+                         } else {
+                             header.appendChild(link);
+                         }
+
+                         link.addEventListener('click', function(e) {
+                             e.preventDefault();
+                             const url = window.location.origin + window.location.pathname + '#' + id;
+
+                             if (navigator.clipboard && navigator.clipboard.writeText) {
+                                 navigator.clipboard.writeText(url).then(() => {
+                                     const originalText = link.textContent;
+                                     link.textContent = '✓';
+                                     setTimeout(() => {
+                                         link.textContent = originalText;
+                                     }, 1000);
+                                 }).catch(err => {
+                                     console.warn('Failed to copy to clipboard', err);
+                                     window.location.hash = id;
+                                 });
+                             } else {
+                                 window.location.hash = id;
+                             }
+                         });
+                     });
+                 }
+                 addHeadingLinks();
+
+                 function addNextHeadingButtons() {
+                     const headers = Array.from(content.querySelectorAll('h1, h2, h3, h4, h5, h6, h7, h8, h9'));
+
+                     headers.forEach((header, index) => {
+                         // Skip if button already exists
+                         if (header.querySelector('.heading-next')) return;
+
+                         // Find next heading
+                         const nextHeader = headers[index + 1];
+                         if (!nextHeader) return; // No next heading
+
+                         const nextId = nextHeader.getAttribute('id');
+                         if (!nextId) return;
+
+                         const nextBtn = document.createElement('button');
+                         nextBtn.className = 'heading-next';
+                         nextBtn.type = 'button';
+                         nextBtn.textContent = '↓';
+                         nextBtn.title = 'Jump to next heading';
+
+                         // Insert after the heading link, before the pin button
+                         const headingLink = header.querySelector('.heading-link');
+                         const pinBtn = header.querySelector('.toc-pin-btn');
+
+                         if (pinBtn) {
+                             header.insertBefore(nextBtn, pinBtn);
+                         } else if (headingLink) {
+                             headingLink.after(nextBtn);
+                         } else {
+                             header.appendChild(nextBtn);
+                         }
+
+                         nextBtn.addEventListener('click', function(e) {
+                             e.preventDefault();
+                             nextHeader.scrollIntoView({ behavior: 'smooth', block: 'start' });
+                             // Update URL hash
+                             history.pushState(null, null, '#' + nextId);
+                         });
+                     });
+                 }
+                 addNextHeadingButtons();
+
+                 let mobileTocBtn = document.getElementById('mobile-toc-toggle');
+                 if (!mobileTocBtn) {
+                     mobileTocBtn = document.createElement('button');
+                     mobileTocBtn.id = 'mobile-toc-toggle';
+                     mobileTocBtn.type = 'button';
+                     mobileTocBtn.textContent = 'TOC';
+                     document.body.appendChild(mobileTocBtn);
+                 }
+
+                 let mobilePinnedBtn = document.getElementById('mobile-pinned-toggle');
+                 if (!mobilePinnedBtn) {
+                     mobilePinnedBtn = document.createElement('button');
+                     mobilePinnedBtn.id = 'mobile-pinned-toggle';
+                     mobilePinnedBtn.type = 'button';
+                     mobilePinnedBtn.textContent = 'Pinned';
+                     document.body.appendChild(mobilePinnedBtn);
+                 }
+
+                 function anyMobilePanelOpen() {
+                     return toc.classList.contains('mobile-visible') ||
+                         pinnedPanel.classList.contains('mobile-visible');
+                 }
+
+                 function updateBodyMobilePanelState() {
+                     if (anyMobilePanelOpen()) body.classList.add('mobile-panel-open');
+                     else body.classList.remove('mobile-panel-open');
+                 }
+
+                 document.addEventListener('click', function(e) {
+                     if (window.innerWidth > 1000) return;
+
+                     if (!anyMobilePanelOpen()) return;
+
+                     const clickedInsideToc = toc.contains(e.target);
+                     const clickedInsidePinned = pinnedPanel.contains(e.target);
+                     const clickedTocBtn = mobileTocBtn.contains(e.target);
+                     const clickedPinnedBtn = mobilePinnedBtn.contains(e.target);
+
+                     const clickedInteractive =
+                           e.target.tagName === 'A' ||
+                           e.target.tagName === 'BUTTON' ||
+                           e.target.tagName === 'INPUT' ||
+                           e.target.tagName === 'TEXTAREA' ||
+                           e.target.closest('a') ||
+                           e.target.closest('button');
+
+                     if (!clickedInsideToc && !clickedInsidePinned && !clickedTocBtn && !clickedPinnedBtn && !clickedInteractive) {
+                         toc.classList.remove('mobile-visible');
+                         pinnedPanel.classList.remove('mobile-visible');
+                         updateBodyMobilePanelState();
+                     }
+                 });
+
+                 mobileTocBtn.addEventListener('click', function() {
+                     const isOpen = toc.classList.toggle('mobile-visible');
+                     if (isOpen) {
+                         pinnedPanel.classList.remove('mobile-visible');
+                     }
+                     updateBodyMobilePanelState();
+                 });
+
+                 mobilePinnedBtn.addEventListener('click', function() {
+                     const isOpen = pinnedPanel.classList.toggle('mobile-visible');
+                     if (isOpen) {
+                         toc.classList.remove('mobile-visible');
+                     }
+                     updateBodyMobilePanelState();
+                 });
+
+                 const pinnedItems = new Map();
+                 let initiallyPinnedHrefs = new Set();
+
+                 function loadFromStorage() {
+                     try {
+                         const raw = window.localStorage && localStorage.getItem(STORAGE_KEY);
+                         if (!raw) return;
+                         const arr = JSON.parse(raw);
+                         if (!Array.isArray(arr)) return;
+                         initiallyPinnedHrefs = new Set(arr);
+                     } catch (e) {
+                         console.warn('Pinned: failed to load from localStorage', e);
+                     }
+                 }
+
+                 function saveToStorage() {
+                     try {
+                         if (!window.localStorage) return;
+                         const arr = [];
+                         pinnedItems.forEach((entry, href) => {
+                             if (entry.li) arr.push(href);
+                         });
+                         localStorage.setItem(STORAGE_KEY, JSON.stringify(arr));
+                     } catch (e) {
+                         console.warn('Pinned: failed to save to localStorage', e);
+                     }
+                 }
+
+                 function sortPinnedList() {
+                     const items = Array.from(pinnedList.children).map(li => {
+                         const link = li.querySelector('a');
+                         return {
+                             li: li,
+                             text: link ? link.textContent.trim().toLowerCase() : ''
+                         };
+                     });
+                     items.sort((a, b) => a.text.localeCompare(b.text));
+                     items.forEach(item => pinnedList.appendChild(item.li));
+                 }
+
+                 function hidePinnedPanel() {
+                     pinnedPanel.classList.add('hidden');
+                     content.classList.add('pinned-hidden');
+                     showBtn.classList.add('visible');
+                 }
+
+                 function showPinnedPanel() {
+                     pinnedPanel.classList.remove('hidden');
+                     content.classList.remove('pinned-hidden');
+                     showBtn.classList.remove('visible');
+                 }
+
+                 toggleBtn.addEventListener('click', hidePinnedPanel);
+                 showBtn.addEventListener('click', showPinnedPanel);
+
+                 clearAllBtn.addEventListener('click', function() {
+                     if (pinnedItems.size === 0) return;
+
+                     const confirmed = confirm('Are you sure you want to clear all pinned items?');
+                     if (!confirmed) return;
+
+                     pinnedItems.forEach((entry, href) => {
+                         if (entry.li && entry.li.parentElement) {
+                             entry.li.parentElement.removeChild(entry.li);
+                         }
+                         entry.li = null;
+                         entry.btns.forEach(b => b.textContent = '[pin]');
+                     });
+
+                     saveToStorage();
+                 });
+
+                 function attachPinBehavior(pinBtn, href, text) {
+                     if (!href) return;
+
+                     if (!pinnedItems.has(href)) {
+                         pinnedItems.set(href, { li: null, btns: new Set(), text: text });
+                     }
+                     const entry = pinnedItems.get(href);
+                     entry.btns.add(pinBtn);
+
+                     pinBtn.textContent = entry.li ? '[unpin]' : '[pin]';
+
+                     pinBtn.addEventListener('click', function(e) {
+                         e.preventDefault();
+                         e.stopPropagation();
+                         const current = pinnedItems.get(href);
+                         if (!current) return;
+
+                         if (current.li) {
+                             if (current.li.parentElement) {
+                                 current.li.parentElement.removeChild(current.li);
+                             }
+                             current.li = null;
+                             current.btns.forEach(b => b.textContent = '[pin]');
+                             saveToStorage();
+                         } else {
+                             const li = document.createElement('li');
+
+                             const a = document.createElement('a');
+                             a.href = href;
+                             a.textContent = current.text;
+
+                             const removeBtn = document.createElement('button');
+                             removeBtn.className = 'pin-remove';
+                             removeBtn.type = 'button';
+                             removeBtn.textContent = '✕';
+                             removeBtn.addEventListener('click', () => {
+                                 const cur = pinnedItems.get(href);
+                                 if (!cur) return;
+                                 if (cur.li && cur.li.parentElement) {
+                                     cur.li.parentElement.removeChild(cur.li);
+                                 }
+                                 cur.li = null;
+                                 cur.btns.forEach(b => b.textContent = '[pin]');
+                                 saveToStorage();
+                             });
+
+                             li.appendChild(a);
+                             li.appendChild(removeBtn);
+                             pinnedList.appendChild(li);
+
+                             current.li = li;
+                             current.btns.forEach(b => b.textContent = '[unpin]');
+
+                             sortPinnedList();
+                             saveToStorage();
+                         }
+                     });
+                 }
+
+                 loadFromStorage();
+
+                 const tocLinks = document.querySelectorAll('#text-table-of-contents a');
+                 tocLinks.forEach(link => {
+                     if (link.parentElement && link.parentElement.classList.contains('toc-entry')) {
+                         return;
+                     }
+                     const li = link.closest('li');
+                     if (!li) return;
+
+                     const wrapper = document.createElement('span');
+                     wrapper.className = 'toc-entry';
+                     li.insertBefore(wrapper, link);
+                     wrapper.appendChild(link);
+
+                     const pinBtn = document.createElement('button');
+                     pinBtn.className = 'toc-pin-btn';
+                     pinBtn.type = 'button';
+                     pinBtn.textContent = '[pin]';
+                     wrapper.appendChild(pinBtn);
+
+                     const href = link.getAttribute('href');
+                     const text = link.textContent.trim();
+                     attachPinBehavior(pinBtn, href, text);
+                 });
+
+                 const headers = content.querySelectorAll('h2, h3, h4, h5, h6, h7, h8, h9');
+                 headers.forEach(header => {
+                     const id = header.getAttribute('id');
+                     if (!id) return;
+                     if (header.querySelector('.toc-pin-btn')) return;
+
+                     const href = '#' + id;
+                     const text = header.textContent.trim();
+
+                     const pinBtn = document.createElement('button');
+                     pinBtn.className = 'toc-pin-btn';
+                     pinBtn.type = 'button';
+                     pinBtn.textContent = '[pin]';
+                     pinBtn.style.marginLeft = '0.8rem';
+                     pinBtn.style.fontSize  = '0.75em';
+
+                     header.appendChild(pinBtn);
+                     attachPinBehavior(pinBtn, href, text);
+                 });
+
+                 initiallyPinnedHrefs.forEach(href => {
+                     const entry = pinnedItems.get(href);
+                     if (!entry) return;
+
+                     const li = document.createElement('li');
+
+                     const a = document.createElement('a');
+                     a.href = href;
+                     a.textContent = entry.text;
+
+                     const removeBtn = document.createElement('button');
+                     removeBtn.className = 'pin-remove';
+                     removeBtn.type = 'button';
+                     removeBtn.textContent = '✕';
+                     removeBtn.addEventListener('click', () => {
+                         const cur = pinnedItems.get(href);
+                         if (!cur) return;
+                         if (cur.li && cur.li.parentElement) {
+                             cur.li.parentElement.removeChild(cur.li);
+                         }
+                         cur.li = null;
+                         cur.btns.forEach(b => b.textContent = '[pin]');
+                         saveToStorage();
+                     });
+
+                     li.appendChild(a);
+                     li.appendChild(removeBtn);
+                     pinnedList.appendChild(li);
+
+                     entry.li = li;
+                     entry.btns.forEach(b => b.textContent = '[unpin]');
+                 });
+
+                 sortPinnedList();
+                 saveToStorage();
+             });
+         })();
+     </script>
+     "
 #+end_src
 
 #+RESULTS:
@@ -861,7 +901,7 @@ I also add this javascript to add header pinning functionality to the site, usin
       attachPinBehavior(pinBtn, href, text);
     });
 
-    const headers = content.querySelectorAll('h2, h3, h4, h5, h6');
+    const headers = content.querySelectorAll('h2, h3, h4, h5, h6, h7, h8, h9');
     headers.forEach(header => {
       const id = header.getAttribute('id');
       if (!id) return;
@@ -32538,7 +32578,7 @@ This is the stylesheet used by the [[#h:12880c64-229c-4063-9eea-387a97490676][HT
       width: calc(100vw - 300px);
   }
 
-  h1, h2, h3, h4, h5, h6 {
+  h1, h2, h3, h4, h5, h6, h7, h8, h9 {
       color: #70e1e8;
       font-weight: 500;
       margin-top: 2.2rem;
@@ -32550,6 +32590,9 @@ This is the stylesheet used by the [[#h:12880c64-229c-4063-9eea-387a97490676][HT
   h4 { font-size: 1.2rem; }
   h5 { font-size: 1.1rem; }
   h6 { font-size: 1.0rem; }
+  h7 { font-size: 0.95rem; }
+  h8 { font-size: 0.925rem; }
+  h9 { font-size: 0.9rem; }
 
   a {
       color: #5ec4ff;
@@ -32758,6 +32801,39 @@ This is the stylesheet used by the [[#h:12880c64-229c-4063-9eea-387a97490676][HT
       color: #5ec4ff;
   }
 
+  .heading-next {
+      opacity: 0;
+      visibility: hidden;
+      transition: opacity 0.2s, visibility 0.2s;
+      margin-left: 0.5rem;
+      color: #718ca1;
+      text-decoration: none;
+      font-size: 0.8em;
+      vertical-align: middle;
+      cursor: pointer;
+      background: none;
+      border: none;
+      padding: 0;
+  }
+
+  .heading-next:hover {
+      color: #5ec4ff;
+      text-decoration: none;
+  }
+
+  h1:hover .heading-next,
+  h2:hover .heading-next,
+  h3:hover .heading-next,
+  h4:hover .heading-next,
+  h5:hover .heading-next,
+  h6:hover .heading-next,
+  h7:hover .heading-next,
+  h8:hover .heading-next,
+  h9:hover .heading-next {
+      opacity: 1;
+      visibility: visible;
+  }
+
   @media (max-width: 1600px) {
       #content {
           max-width: 100%;
@@ -32878,7 +32954,10 @@ This is the stylesheet used by the [[#h:12880c64-229c-4063-9eea-387a97490676][HT
   h3:hover .heading-link,
   h4:hover .heading-link,
   h5:hover .heading-link,
-  h6:hover .heading-link {
+  h6:hover .heading-link,
+  h7:hover .heading-link,
+  h8:hover .heading-link,
+  h9:hover .heading-link {
       opacity: 1;
       visibility: visible;
   }
@@ -32904,7 +32983,10 @@ This is the stylesheet used by the [[#h:12880c64-229c-4063-9eea-387a97490676][HT
   h3 .toc-pin-btn,
   h4 .toc-pin-btn,
   h5 .toc-pin-btn,
-  h6 .toc-pin-btn {
+  h6 .toc-pin-btn,
+  h7 .toc-pin-btn,
+  h8 .toc-pin-btn,
+  h9 .toc-pin-btn {
       opacity: 0;
       visibility: hidden;
       transition: opacity 0.2s, visibility 0.2s;
@@ -32915,7 +32997,10 @@ This is the stylesheet used by the [[#h:12880c64-229c-4063-9eea-387a97490676][HT
   h3:hover .toc-pin-btn,
   h4:hover .toc-pin-btn,
   h5:hover .toc-pin-btn,
-  h6:hover .toc-pin-btn {
+  h6:hover .toc-pin-btn,
+  h7:hover .toc-pin-btn,
+  h8:hover .toc-pin-btn,
+  h9:hover .toc-pin-btn {
       opacity: 1;
       visibility: visible;
   }