From 1c9995a6ecf36cded4f1952f75ed95b463617174 Mon Sep 17 00:00:00 2001
From: reugn <reugpro@gmail.com>
Date: Fri, 2 Jan 2026 17:51:03 +0200
Subject: [PATCH] docs: improve documentation and add theme toggle

---
 docs/Gemfile                             |  4 +-
 docs/_config.yml                         | 10 ++++-
 docs/_includes/head_custom.html          | 54 ++++++++++++++++++++++++
 docs/_includes/header_custom.html        |  3 ++
 docs/assets/css/just-the-docs-dark.scss  |  4 ++
 docs/assets/css/just-the-docs-light.scss |  1 +
 docs/configuration/index.md              |  2 +-
 docs/configuration/run.md                |  6 +--
 8 files changed, 77 insertions(+), 7 deletions(-)
 create mode 100644 docs/_includes/header_custom.html
 create mode 100644 docs/assets/css/just-the-docs-dark.scss
 create mode 100644 docs/assets/css/just-the-docs-light.scss

diff --git a/docs/Gemfile b/docs/Gemfile
index 77f620e..e08fb53 100644
--- a/docs/Gemfile
+++ b/docs/Gemfile
@@ -1,7 +1,7 @@
 source "https://rubygems.org"
 
-gem "jekyll", "~> 4.3"
-gem "just-the-docs"
+gem "jekyll", "~> 4.4.1"
+gem "just-the-docs" , "~> 0.11.0" 
 gem "webrick"
 gem "jekyll-seo-tag"
 gem "listen"
diff --git a/docs/_config.yml b/docs/_config.yml
index 9fe0bb6..d5211cd 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -11,8 +11,16 @@ url: "https://reugn.github.io"
 # Theme
 theme: just-the-docs
 
+# Sass (silence deprecation warnings from theme)
+sass:
+  quiet_deps: true
+  silence_deprecations:
+    - import
+    - global-builtin
+    - color-functions
+
 # Color scheme
-color_scheme: dark
+color_scheme: light
 
 # Aux links (top right)
 aux_links:
diff --git a/docs/_includes/head_custom.html b/docs/_includes/head_custom.html
index 47cc550..f3b13e1 100644
--- a/docs/_includes/head_custom.html
+++ b/docs/_includes/head_custom.html
@@ -1,2 +1,56 @@
 <link rel="icon" href="{{ '/assets/images/favicon.svg' | relative_url }}" type="image/svg+xml">
 
+<!-- Determine theme before loading stylesheets -->
+<script>
+  var jtdTheme = localStorage.getItem('jtd-theme') || 'light';
+  document.documentElement.setAttribute('data-theme', jtdTheme);
+</script>
+
+<!-- Theme stylesheets - disabled state set dynamically -->
+<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-light.css' | relative_url }}" id="jtd-light">
+<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-dark.css' | relative_url }}" id="jtd-dark">
+<script>
+  (function() {
+    var isDark = jtdTheme === 'dark';
+    document.getElementById('jtd-light').disabled = isDark;
+    document.getElementById('jtd-dark').disabled = !isDark;
+  })();
+
+  function toggleTheme() {
+    var current = document.documentElement.getAttribute('data-theme') || 'light';
+    var newTheme = current === 'light' ? 'dark' : 'light';
+    
+    document.documentElement.setAttribute('data-theme', newTheme);
+    
+    var lightCss = document.getElementById('jtd-light');
+    var darkCss = document.getElementById('jtd-dark');
+    var isDark = newTheme === 'dark';
+    if (lightCss) lightCss.disabled = isDark;
+    if (darkCss) darkCss.disabled = !isDark;
+    
+    try {
+      localStorage.setItem('jtd-theme', newTheme);
+    } catch (e) {}
+  }
+</script>
+
+<style>
+  .theme-toggle {
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 4px 8px;
+    font-size: 1.1rem;
+    color: var(--link-color);
+    vertical-align: middle;
+    margin-right: 0.5rem;
+  }
+  .theme-toggle:hover {
+    opacity: 0.7;
+  }
+  /* Show correct icon based on theme */
+  .icon-sun { display: none; }
+  .icon-moon { display: inline; }
+  [data-theme="dark"] .icon-sun { display: inline; }
+  [data-theme="dark"] .icon-moon { display: none; }
+</style>
diff --git a/docs/_includes/header_custom.html b/docs/_includes/header_custom.html
new file mode 100644
index 0000000..f8f4891
--- /dev/null
+++ b/docs/_includes/header_custom.html
@@ -0,0 +1,3 @@
+<button class="theme-toggle" onclick="toggleTheme()" title="Toggle theme">
+  <span class="icon-moon">🌑</span><span class="icon-sun">☀️</span>
+</button>
diff --git a/docs/assets/css/just-the-docs-dark.scss b/docs/assets/css/just-the-docs-dark.scss
new file mode 100644
index 0000000..cb5d699
--- /dev/null
+++ b/docs/assets/css/just-the-docs-dark.scss
@@ -0,0 +1,4 @@
+@import "just-the-docs";
+:root {
+  --color-scheme: dark;
+}
diff --git a/docs/assets/css/just-the-docs-light.scss b/docs/assets/css/just-the-docs-light.scss
new file mode 100644
index 0000000..c49e032
--- /dev/null
+++ b/docs/assets/css/just-the-docs-light.scss
@@ -0,0 +1 @@
+@import "css/just-the-docs.scss";
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 0eadfa6..4b200bd 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -23,7 +23,7 @@ Or create `.github-ci.yaml` manually in your repository root.
 
 ```yaml
 run:
-  timeout: 5m          # timeout for GitHub API operations
+  timeout: 5m          # maximum duration for command execution
   issues-exit-code: 1  # exit code when issues are found
 
 linters:
diff --git a/docs/configuration/run.md b/docs/configuration/run.md
index 49d3ecb..f15ff23 100644
--- a/docs/configuration/run.md
+++ b/docs/configuration/run.md
@@ -19,7 +19,7 @@ run:
 
 ### timeout
 
-Maximum time allowed for GitHub API operations.
+Maximum time allowed for command execution.
 
 | Value | Description |
 |-------|-------------|
@@ -28,11 +28,11 @@ Maximum time allowed for GitHub API operations.
 | `5m` | 5 minutes (default) |
 | `1h` | 1 hour |
 
-This is useful for CI/CD environments with strict time limits. If the timeout is reached, the command will fail.
+When the timeout is reached, the command is cancelled.
 
 ```yaml
 run:
-  timeout: 2m  # Fail if API calls take longer than 2 minutes
+  timeout: 2m  # Maximum duration for the entire command execution
 ```
 
 ### issues-exit-code