Reorganize docs under docs/ and update Jekyll navigation/permalinks

yaravind · yaravind · commit 8287427dc5da · 2026-03-03T12:18:13.000-05:00
diff --git a/README.md b/README.md
@@ -176,19 +176,19 @@ Optional modes:
 
 ## FAQ
 
-See [faq.md](faq.md).
+See [faq](docs/faq.md).
 
 ---
 
 ## Scripts
 
-See [scripts.md](scripts.md) for a complete table of scripts and descriptions.
+See [scripts](docs/scripts.md) for a complete table of scripts and descriptions.
 
 ---
 
 ## Other
 
-For Git aliases, package management tips, IntelliJ integration, and more, see [details.md](details.md).
+For Git aliases, package management tips, IntelliJ integration, and more, see [details](docs/details.md).
 
 ---
 
diff --git a/_config.yml b/_config.yml
@@ -25,22 +25,30 @@ theme: jekyll-theme-cayman
 
 # Navigation pages
 header_pages:
-  - faq.md
-  - details.md
-  - scripts.md
+  - docs/faq.md
+  - docs/details.md
+  - docs/scripts.md
   - CONTRIBUTING.md
+  - docs/index.md
 
 # Markdown settings
 markdown: kramdown
 kramdown:
   input: GFM
 
+# Ensure docs pages are rendered with the theme layout
+defaults:
+  - scope:
+      path: "docs"
+      type: "pages"
+    values:
+      layout: default
+
 # Exclude files not needed in the built site
 exclude:
   - scripts/
   - config/
   - assets/triples.dot
-  - docs/
   - "*.sh"
   - "*.ps1"
   - .github/
diff --git a/docs/details.md b/docs/details.md
@@ -1,3 +1,8 @@
+---
+title: Details
+permalink: /details/
+---
+
 # Details
 
 ## Table of Contents
@@ -359,7 +364,7 @@ upgrade to latest
 Configure IntelliJ to use GitHub Issues as a task manager. This allows you to create, view, and manage GitHub issues
 directly.
 
-![Configure Servers](assets/intellij-tasks.png)
+![Configure Servers]({{ '/assets/intellij-tasks.png' | relative_url }})
 
 ---
 
@@ -388,7 +393,7 @@ nested folders
 
 ## Reference
 
-- [Notes](docs/notes.md)
+- [Notes]({{ '/docs/notes/' | relative_url }})
 - [The Linux Documentation Project](http://www.tldp.org/guides.html)
 - [Stackoverflow](https://stackoverflow.com)
 - [Git Gist](https://gist.github.com/eyecatchup/3fb7ef0c0cbdb72412fc)
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,10 +1,15 @@
+---
+title: FAQ
+permalink: /faq/
+---
+
 ## Frequently Asked Questions
 
 ## Question 1
 
 ERROR: winget (App Installer) is not installed (Screenshot below).
 
-![winget not installed](assets/issue-winget-not-installed.png)
+![winget not installed]({{ '/assets/issue-winget-not-installed.png' | relative_url }})
 
 ### Solution
 
@@ -174,4 +179,3 @@ x64
 
 
 Awesome, all set!
-```
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,28 @@
+---
+title: Documentation
+permalink: /docs/
+---
+
+# Documentation
+
+Use this section for deeper references and implementation notes.
+
+## Core Guides
+
+- [FAQ]({{ '/faq/' | relative_url }})
+- [Details]({{ '/details/' | relative_url }})
+- [Scripts]({{ '/scripts/' | relative_url }})
+
+## Windows Setup Guides
+
+- [VS Code extension setup]({{ '/docs/windows-vscode-setup/' | relative_url }})
+- [Taskbar setup]({{ '/docs/windows-taskbar-setup/' | relative_url }})
+
+## Testing
+
+- [Dry-run tests]({{ '/docs/tests/' | relative_url }})
+
+## Reference
+
+- [Notes]({{ '/docs/notes/' | relative_url }})
+- [VS Code extension catalog]({{ '/docs/vscode-info/' | relative_url }})
diff --git a/docs/notes.md b/docs/notes.md
@@ -1,3 +1,8 @@
+---
+title: Notes
+permalink: /docs/notes/
+---
+
 # 1. Notes
 
 ## 1.1. Table of Contents
diff --git a/docs/scripts.md b/docs/scripts.md
@@ -1,3 +1,8 @@
+---
+title: Scripts
+permalink: /scripts/
+---
+
 # Scripts
 
 This file documents the repository's helper scripts and what they do. For usage details, run the individual scripts with `-Help` (Windows PowerShell scripts) or check the comments at the top of each script.
@@ -20,4 +25,3 @@ This file documents the repository's helper scripts and what they do. For usage
 
 
 > Tip: For Windows PowerShell scripts, run them from an elevated PowerShell session and use `-Help` to see runtime options such as `-DryRun`, `-Interactive`, and `-Silent`.
-
diff --git a/docs/taskbar_setup_windows/README.md b/docs/taskbar_setup_windows/README.md
@@ -1,3 +1,8 @@
+---
+title: Windows Taskbar Setup
+permalink: /docs/windows-taskbar-setup/
+---
+
 # Windows Taskbar Setup
 
 This folder contains a minimal Windows Taskbar setup script that pins and unpins apps based on a config file.
diff --git a/docs/tests/README.md b/docs/tests/README.md
@@ -1,3 +1,8 @@
+---
+title: Dry-Run Tests
+permalink: /docs/tests/
+---
+
 # Dry-Run Tests
 
 This repo includes lightweight dry-run tests for both macOS and Windows scripts.
@@ -25,4 +30,3 @@ Run the Windows script checks from PowerShell:
 The Windows dry-run checks:
 - Parse each PowerShell script for syntax errors.
 - Run safe `-DryRun` checks for Taskbar and VS Code setup.
-
diff --git a/docs/vscode-info.md b/docs/vscode-info.md
@@ -1,3 +1,8 @@
+---
+title: VS Code Extension Catalog
+permalink: /docs/vscode-info/
+---
+
 | Name                                      | Description                                                                                                          |
 |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
 | vscjava.vscode-java-pack                  | Java Extension Pack: Popular extensions for Java development.                                                        |
diff --git a/docs/vscode_setup_windows/README.md b/docs/vscode_setup_windows/README.md
@@ -1,3 +1,8 @@
+---
+title: Windows VS Code Extension Setup
+permalink: /docs/windows-vscode-setup/
+---
+
 # Windows VS Code Extension Setup
 
 This script installs VS Code extensions listed in `config/vscode.txt`.
