docs: improve documentation and add theme toggle (#17)

Author: reugn

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"

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:

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>

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>

docs/assets/css/just-the-docs-dark.scss

@@ -0,0 +1,4 @@
+@import "just-the-docs";
+:root {
+  --color-scheme: dark;
+}

docs/assets/css/just-the-docs-light.scss

@@ -0,0 +1 @@
+@import "css/just-the-docs.scss";

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:

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