docs: transformed README into a visual, picture-book style cyber guide #18
Conversation
Revamped the README with new visuals, OS logos, GIFs, and improved installation sections. Made it more user-friendly, organised, and visually engaging for beginners.
WalkthroughREADME.md was replaced with a comprehensive "Kali Magic" README focused on a portable, rootless Kali/NetHunter experience on Android. It adds supported-OS details and logos, Quick Install and manual flows (Termux/LinuxDroid/proot-distro), GIF optimization script guidance, visual demos, usage examples, prerequisites, and contribution/licensing sections. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant README as README (docs)
participant Installer as Installer Script
participant Termux
participant LinuxDroid
participant Proot as proot-distro
participant Kali as Kali/NetHunter
rect rgb(230, 248, 230)
Note over README,User: Quick Install flow (documented)
end
User->>README: follow Quick Install steps
User->>Installer: download & run installer (bash)
Installer->>Termux: detect environment / prompt
alt LinuxDroid available
Installer->>LinuxDroid: offer LinuxDroid extras
end
Installer->>Proot: create/enter proot-distro (Debian)
Proot->>Kali: bootstrap Kali chroot / NetHunter rootless components
Kali-->>User: ready shell / GUI instructions
note right of Installer: Optional: run `scripts/optimize_gifs.sh` for demos
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 2 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (4)
README.md (4)
11-27: Move asset setup instructions to separate guide.These contributor/maintainer setup instructions belong in
CONTRIBUTING.mdor a dedicated setup guide rather than the main README. Embedding setup steps in the primary documentation creates confusion about whether end-users need to run these commands. The README should focus on user-facing content.Consider creating a
CONTRIBUTING.mdordocs/SETUP.mdfile with these instructions and replacing lines 11-27 with a simple reference like:> **For maintainers:** See [CONTRIBUTING.md](CONTRIBUTING.md) to set up demo assets.
146-180: Move bash script to separate file.The 35-line
optimize_gifs.shscript is embedded inline in the README, which reduces readability. Since the script is meant to be saved toscripts/optimize_gifs.sh(per lines 182-186), move it to the actual file and reference it from the README.Replace lines 146-180 with a brief reference:
To optimize GIFs for the README, use the included script: \`\`\`bash ./scripts/optimize_gifs.sh 640 15 git add assets/gifs/optimized/* git commit -m "Add optimized README GIFs" git push origin main \`\`\` See `scripts/optimize_gifs.sh` for details.Then create
scripts/optimize_gifs.shwith the full script content.
11-27: Remove or simplify external asset download instructions.The README includes detailed instructions for downloading images from Wikimedia Commons (lines 11-27). While this improves documentation, it creates maintenance issues:
- External URLs may break or become unavailable
- README images won't render until contributors manually download them
- This adds friction for new contributors
Recommendation: Either:
- Option A (Preferred): Commit image assets to the repository under
assets/gifs/, removing the need for external downloads- Option B: Remove the asset setup instructions and accept that the README will have limited visual enhancement until images are manually added
- Option C: Document this as an optional enhancement step in
CONTRIBUTING.mdrather than the main READMEThis ties into the earlier comment about moving asset setup to a separate contribution guide.
1-50: Minor: Reduce exclamation mark density for professional tone.Static analysis flags 5 exclamation marks in ~2312 characters as potentially excessive. While the current tone is engaging (good for educational content), reducing exclamation marks slightly can improve perceived professionalism without losing enthusiasm.
Consider replacing some exclamation-based emphasis with:
- Em-dashes for emphasis
- Stronger adjectives
- Strategic emoji use (already well-used throughout)
This is a very minor style concern and not a blocker; feel free to defer or skip if the current tone aligns with project brand.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~71-~71: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2312 characters long)
Context: ...ble, server-ready Linux distribution. | 
🪛 markdownlint-cli2 (0.18.1)
README.md
7-7: No empty links
(MD042, no-empty-links)
33-33: Link fragments should be valid
(MD051, link-fragments)
34-34: Link fragments should be valid
(MD051, link-fragments)
35-35: Link fragments should be valid
(MD051, link-fragments)
36-36: Link fragments should be valid
(MD051, link-fragments)
37-37: Link fragments should be valid
(MD051, link-fragments)
38-38: Link fragments should be valid
(MD051, link-fragments)
39-39: Link fragments should be valid
(MD051, link-fragments)
40-40: Link fragments should be valid
(MD051, link-fragments)
41-41: Link fragments should be valid
(MD051, link-fragments)
42-42: Link fragments should be valid
(MD051, link-fragments)
43-43: Link fragments should be valid
(MD051, link-fragments)
44-44: Link fragments should be valid
(MD051, link-fragments)
45-45: Link fragments should be valid
(MD051, link-fragments)
46-46: Link fragments should be valid
(MD051, link-fragments)
47-47: Link fragments should be valid
(MD051, link-fragments)
48-48: Link fragments should be valid
(MD051, link-fragments)
49-49: Link fragments should be valid
(MD051, link-fragments)
README.md
Outdated
|
|
||
| --- | ||
|
|
||
| > **Before you paste (optional but recommended):** |
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
README.md (2)
99-141: Restructure Quick Install into clear alternative paths (duplicate concern).The Quick Install section mixes two installation flows without clear boundaries:
- Direct Termux installation (lines 100–118): updates, installs nethunter-termux, optional extras
- proot-distro + Debian (lines 119–141): sets up a Debian container, installs nethunter-termux again inside it
Problems:
- No "Option A" / "Option B" labeling to disambiguate intent
install-nethunter-termuxappears twice (line 106 & line 127), suggesting the user should do both—which is confusing- Commands after
proot-distro login debian(lines 125–141) are executed inside the container, but this is not explicitly labeled- Line 109 (wget for menu.sh) has awkward formatting
Per prior review feedback, restructure this section clearly. Choose one of these approaches:
Approach 1: Sequential steps — if users should do Termux → then proot-distro → then Debian, make this explicit with clear step labels and explain why nethunter is needed twice.
Approach 2: Mutually exclusive options — if users choose either Termux or proot-distro, split into:
## 🚀 Quick Install ### Option A: Direct Termux Installation [commands for Termux only] ### Option B: Debian via proot-distro [commands to set up proot-distro + Debian] [commands to run inside Debian container] ## Usage Examples [shared usage examples for both paths]
7-7: Fix empty badge link (MD042) — duplicate of prior issue.The Downloads badge still has an empty link
()that violates markdown linting. Additionally, the badge repository reference points toParrotSecurityOsForAndroidbut this project isKali-Linux-for-Android.Apply this diff to fix both the empty link and repository mismatch:
-[]() +[](https://github.com/AryanVBW/Kali-Linux-for-Android/releases)
🧹 Nitpick comments (1)
README.md (1)
143-177: Consider moving the GIF optimization script to a dedicated file.The
optimize_gifs.shscript is embedded in the README (lines 143–177) as part of the Quick Install section. While the script itself is well-written, embedding it in documentation is unconventional and creates maintenance burden.Recommended approach: Move this script to
scripts/optimize_gifs.shin the repository and reference it from the README:### Optimize README GIFs The repository includes a GIF optimization script to reduce file sizes: \`\`\`bash # From repository root: ./scripts/optimize_gifs.sh 640 15 \`\`\` See [`scripts/optimize_gifs.sh`](scripts/optimize_gifs.sh) for details. \`\`\`This keeps the README focused on documentation and makes the script reusable and easier to maintain. If this is a one-time contributor setup task, clarify that in the CONTRIBUTING section.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~68-~68: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2177 characters long)
Context: ...ble, server-ready Linux distribution. | 
🪛 markdownlint-cli2 (0.18.1)
README.md
7-7: No empty links
(MD042, no-empty-links)
30-30: Link fragments should be valid
(MD051, link-fragments)
31-31: Link fragments should be valid
(MD051, link-fragments)
32-32: Link fragments should be valid
(MD051, link-fragments)
33-33: Link fragments should be valid
(MD051, link-fragments)
34-34: Link fragments should be valid
(MD051, link-fragments)
35-35: Link fragments should be valid
(MD051, link-fragments)
36-36: Link fragments should be valid
(MD051, link-fragments)
37-37: Link fragments should be valid
(MD051, link-fragments)
38-38: Link fragments should be valid
(MD051, link-fragments)
39-39: Link fragments should be valid
(MD051, link-fragments)
40-40: Link fragments should be valid
(MD051, link-fragments)
41-41: Link fragments should be valid
(MD051, link-fragments)
42-42: Link fragments should be valid
(MD051, link-fragments)
43-43: Link fragments should be valid
(MD051, link-fragments)
44-44: Link fragments should be valid
(MD051, link-fragments)
45-45: Link fragments should be valid
(MD051, link-fragments)
46-46: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (1)
README.md (1)
11-24: Clarify asset download block intent and relocate if needed.Lines 11–24 contain instructions to download demo GIFs and logos, placed between badges and the TOC. The intent is unclear:
- If these are for contributors setting up the repository, move them to a dedicated
CONTRIBUTINGorDevelopment Setupsection.- If these are for users, explain why they need to run these commands and how the downloaded assets are used.
Current placement interrupts the reader flow and conflates user guidance with potential maintenance tasks.
Clarify the intent, relocate this block appropriately, and add a brief context comment if users are expected to run these commands.
| ## 📖 Table of Contents | ||
| - [About](#about) | ||
| - [Supported Operating Systems](#supported-operating-systems) | ||
| - [Features](#features) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Quick Install](#quick-install) | ||
| - [Manual Installation](#manual-installation) | ||
| - [Kali NetHunter (Rootless)](#kali-nethunter-rootless) | ||
| - [Visual Demos](#visual-demos) | ||
| - [Nmap](#nmap) | ||
| - [Metasploit](#metasploit) | ||
| - [Wireshark](#wireshark) | ||
| - [Installer Walkthrough](#installer-walkthrough) | ||
| - [Usage Examples](#usage-examples) | ||
| - [Installation Link](#installation-link) | ||
| - [Security & Legal Notice](#security--legal-notice) | ||
| - [Contributing & Support](#contributing--support) | ||
| - [Credits & License](#credits--license) |
There was a problem hiding this comment.
🧩 Analysis chain
Verify all Table of Contents sections exist in the complete file.
Static analysis flags all TOC links as invalid (MD051 errors, lines 30–46). The provided code snippet ends at line 187, making it impossible to confirm whether all 15+ referenced sections have corresponding ## headings in the complete file.
The TOC references these sections that are not visible in the provided code:
- Manual Installation
- Kali NetHunter (Rootless)
- Visual Demos (with 4 subsections)
- Usage Examples, Installation Link, Security & Legal Notice, Contributing & Support, Credits & License
Run this verification script to ensure all TOC anchors resolve:
If sections are missing, add them with appropriate heading levels and placeholder content.
🏁 Script executed:
#!/bin/bash
# Extract all TOC link anchors and verify corresponding ## headings exist
echo "=== TOC Anchors (from lines 30-46) ==="
rg -A 16 '📖 Table of Contents' README.md | rg '\(#[^)]+\)' -o | sed 's/[()#]//g' | sort | uniq
echo -e "\n=== Heading Anchors (from ## lines) ==="
rg '^##+ ' README.md | sed 's/^##* //; s/[^a-z0-9 -]//g; s/ /-/g' | tr '[:upper:]' '[:lower:]' | sort | uniq
echo -e "\n=== Checking for missing sections ==="
for section in "manual-installation" "kali-nethunter-rootless" "visual-demos" "nmap" "metasploit" "wireshark" "installer-walkthrough" "usage-examples" "installation-link" "security--legal-notice" "contributing--support" "credits--license"; do
if rg -q "^## .* $section" README.md; then
echo "✓ $section"
else
echo "✗ MISSING: $section"
fi
doneLength of output: 767
I need to run a cleaner verification to get reliable results about which sections actually exist.
🏁 Script executed:
#!/bin/bash
# Get all ## headings directly without complex regex
echo "=== All ## Headings (raw) ==="
rg '^## ' README.md | head -20
echo -e "\n=== Heading count ==="
rg '^## ' README.md | wc -l
echo -e "\n=== All ### Subsection headings ==="
rg '^### ' README.md | head -20Length of output: 241
I need to rerun the verification with the repository cloned.
🏁 Script executed:
#!/bin/bash
# Get all ## headings directly without complex regex
echo "=== All ## Headings (raw) ==="
rg '^## ' README.md | head -30
echo -e "\n=== Heading count ==="
rg '^## ' README.md | wc -l
echo -e "\n=== All ### Subsection headings ==="
rg '^### ' README.md | head -30
echo -e "\n=== Total file lines ==="
wc -l README.mdLength of output: 256
Add 12 missing sections referenced in the Table of Contents or remove them from TOC.
Only 5 of the 15 sections referenced in the TOC (lines 28–46) have corresponding ## headings in the file:
- ✓ About, Supported Operating Systems, Features, Prerequisites, Quick Install
- ✗ Manual Installation, Kali NetHunter (Rootless), Visual Demos, Nmap, Metasploit, Wireshark, Installer Walkthrough, Usage Examples, Installation Link, Security & Legal Notice, Contributing & Support, Credits & License
The file contains only 187 lines with 6 total ## headings. Either add the 12 missing sections with appropriate content, or update the TOC to match the actual file structure.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
30-30: Link fragments should be valid
(MD051, link-fragments)
31-31: Link fragments should be valid
(MD051, link-fragments)
32-32: Link fragments should be valid
(MD051, link-fragments)
33-33: Link fragments should be valid
(MD051, link-fragments)
34-34: Link fragments should be valid
(MD051, link-fragments)
35-35: Link fragments should be valid
(MD051, link-fragments)
36-36: Link fragments should be valid
(MD051, link-fragments)
37-37: Link fragments should be valid
(MD051, link-fragments)
38-38: Link fragments should be valid
(MD051, link-fragments)
39-39: Link fragments should be valid
(MD051, link-fragments)
40-40: Link fragments should be valid
(MD051, link-fragments)
41-41: Link fragments should be valid
(MD051, link-fragments)
42-42: Link fragments should be valid
(MD051, link-fragments)
43-43: Link fragments should be valid
(MD051, link-fragments)
44-44: Link fragments should be valid
(MD051, link-fragments)
45-45: Link fragments should be valid
(MD051, link-fragments)
46-46: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
In README.md around lines 28 to 46 the Table of Contents lists 15 sections but
only 6 corresponding "##" headings exist; reconcile by either adding the 12
missing sections as proper "## <Section Name>" headings (Manual Installation;
Kali NetHunter (Rootless); Visual Demos and its subheadings Nmap, Metasploit,
Wireshark, Installer Walkthrough; Usage Examples; Installation Link; Security &
Legal Notice; Contributing & Support; Credits & License) with brief placeholder
content under each, or remove those entries from the TOC so it matches the file;
ensure each TOC entry exactly matches the heading text (including punctuation)
so anchors work and preserve order/indentation for nested items (Visual Demos ->
Nmap/Metasploit/Wireshark/Installer Walkthrough).
| ## 🐧 Supported Operating Systems | ||
| | OS | Version | Description | Logo | | ||
| |----|---------|-------------|------| | ||
| | **Kali Linux** | Rolling | Advanced penetration testing & security distro. |  | | ||
| | **Parrot Security OS** | Rolling | Forensics, pen-testing, privacy & dev tools. |  | | ||
| | **Ubuntu** | 20.04+ | General-purpose Linux for dev & scripting. |  | | ||
| | **Debian** | 11+ | Stable, server-ready Linux distribution. |  | |
There was a problem hiding this comment.
🧩 Analysis chain
Verify image asset paths exist in the repository.
The Supported Operating Systems table (lines 61–68) references image files from assets/gifs/:
kali-logo.pngparrot-logo.pngubuntu-logo.pngdebian-logo.pnglinuxdroid-install.gif(line 57)
These asset paths should be verified to ensure they:
- Exist in the repository at the specified locations
- Are properly sized (as per PR objectives: "Images should be properly sized to avoid overwhelming the page")
- Are under version control or documented as external assets
Run this script to verify image asset presence and size:
If any assets are missing or external (from Wikimedia), document this clearly in the README or ensure they are committed to the repository.
🏁 Script executed:
#!/bin/bash
# Verify all image assets referenced in README exist and check dimensions
echo "=== Image Assets Referenced in README ==="
rg '!\[.*?\]\(assets/gifs/[^)]+\)' README.md -o
echo -e "\n=== Checking for file existence ==="
for asset in assets/gifs/kali-logo.png assets/gifs/parrot-logo.png assets/gifs/ubuntu-logo.png assets/gifs/debian-logo.png assets/gifs/linuxdroid-install.gif assets/gifs/nmap-scan.gif assets/gifs/metasploit-demo.gif assets/gifs/wireshark-capture.gif; do
if [ -f "$asset" ]; then
size=$(du -h "$asset" | cut -f1)
echo "✓ $asset ($size)"
else
echo "✗ MISSING: $asset"
fi
done
echo -e "\n=== Image Dimensions (if ImageMagick available) ==="
if command -v identify >/dev/null 2>&1; then
for img in assets/gifs/*.{png,gif}; do
[ -f "$img" ] && identify "$img" || true
done
fiLength of output: 684
All referenced image assets are missing from the repository.
The README.md contains 5 image references (lines 57, 62–65) that do not exist in the repository:
assets/gifs/linuxdroid-install.gifassets/gifs/kali-logo.pngassets/gifs/parrot-logo.pngassets/gifs/ubuntu-logo.pngassets/gifs/debian-logo.png
This results in broken image links throughout the documentation. Either:
- Commit these image files to the repository at the referenced paths, or
- Remove the image references and markdown image syntax from the README
🧰 Tools
🪛 LanguageTool
[style] ~68-~68: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2177 characters long)
Context: ...ble, server-ready Linux distribution. | 
🤖 Prompt for AI Agents
In README.md around lines 61 to 68, the README references five image assets that
are missing (assets/gifs/linuxdroid-install.gif, kali-logo.png, parrot-logo.png,
ubuntu-logo.png, debian-logo.png), causing broken image links; fix by either
adding the actual image files into the repository at assets/gifs/ with the exact
filenames and commit them, or remove the markdown image syntax for each missing
file (replace with plain text names or external image URLs) and update the table
entries accordingly; ensure paths and filenames match exactly, run a quick
markdown preview to verify no broken images remain, and commit the change with a
clear message.
2 participants
Updated the README with new OS logos, visuals, and installation sections for better clarity and presentation.
This update makes the README more user-friendly and visually rich.
Closes #2
Summary by CodeRabbit