{"id":30732541,"url":"https://github.com/codecaine-zz/markdown_tutorials","last_synced_at":"2026-04-28T21:34:16.292Z","repository":{"id":312738300,"uuid":"1047585546","full_name":"codecaine-zz/markdown_tutorials","owner":"codecaine-zz","description":"markdown tutorials","archived":false,"fork":false,"pushed_at":"2025-11-06T15:19:32.000Z","size":8240,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T15:27:34.557Z","etag":null,"topics":["bun","bundle","clipboard","clipboard-manager","display","documentation","dynamical-systems","filter","folders","guide","guides","highlighting","homebrew","javascript","markdown","php","python","search","tutorials","vlang"],"latest_commit_sha":null,"homepage":"https://codefreelance.net/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codecaine-zz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-30T18:43:27.000Z","updated_at":"2025-11-06T15:19:37.000Z","dependencies_parsed_at":"2025-09-01T18:35:28.204Z","dependency_job_id":"ba39da59-cc74-4a3e-8d87-2c20a67fdfc1","html_url":"https://github.com/codecaine-zz/markdown_tutorials","commit_stats":null,"previous_names":["codecaine-zz/markdown_tutorials"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codecaine-zz/markdown_tutorials","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fmarkdown_tutorials","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fmarkdown_tutorials/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fmarkdown_tutorials/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fmarkdown_tutorials/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codecaine-zz","download_url":"https://codeload.github.com/codecaine-zz/markdown_tutorials/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fmarkdown_tutorials/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32400866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","bundle","clipboard","clipboard-manager","display","documentation","dynamical-systems","filter","folders","guide","guides","highlighting","homebrew","javascript","markdown","php","python","search","tutorials","vlang"],"created_at":"2025-09-03T17:08:58.436Z","updated_at":"2026-04-28T21:34:16.284Z","avatar_url":"https://github.com/codecaine-zz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Tutorials\n\nA modern, feature-rich web application for browsing and viewing markdown-based tutorials with advanced search, bookmarking, progress tracking, and responsive design.\n\n## 🚀 Latest Features \u0026 Improvements\n\n### Enhanced User Experience\n\n- **🔍 Fuzzy Search System** - Smart search with highlighting, suggestions, and history\n- **📖 Reading Progress Tracking** - Automatic progress tracking with visual indicators\n- **🔖 Advanced Bookmark System** - One-click bookmarking with progress persistence\n- **📱 Quick Actions Menu** - Floating action button with bookmark, history, print, and share\n- **⏱️ Recent History** - Automatically tracks and displays recently viewed tutorials\n- **⌨️ Enhanced Keyboard Shortcuts** - Comprehensive shortcuts for power users\n- **🔔 Smart Notifications** - Toast notifications for user actions and feedback\n- **🎨 Improved Dark Theme** - Complete dark mode support for all features\n- **🖨️ Print-Optimized Styles** - Clean print layout removing navigation elements\n- **♿ Better Accessibility** - Keyboard navigation, focus styles, and ARIA labels\n- **📱 Mobile Enhancements** - Touch-friendly interactions and responsive design\n- **🧭 Right‑rail Sticky Table of Contents** - Always-visible ToC with scrollspy highlighting and persisted visibility\n- **🧰 Code-friendly Layout** - Wider content column, larger inter-column gap, and per-article zoom that doesn’t affect the ToC\n\n\n## Related: neu_markdown_buddy (desktop, web, cloud)\n\nIf you prefer a native desktop experience, check out neu_markdown_buddy — a cross‑platform NeutralinoJS port of this project for macOS, Windows, and Linux.\n\n- Repository: [codecaine-zz/neu_markdown_buddy](https://github.com/codecaine-zz/neu_markdown_buddy)\n- Platforms: macOS, Windows, Linux (desktop); core UI also runs in a regular browser\n- Highlights: advanced navigation, smart search, ToC, code copy, theme + zoom, random tutorial, and persistent UI state\n\nQuick desktop start (summary):\n\n- Install Node.js or Bun and the NeutralinoJS CLI (@neutralinojs/neu)\n- In the neu_markdown_buddy repo: run `neu update`, then `neu run` for dev or `neu build` for distributable binaries\n\nUse your existing tutorials with the desktop app:\n\n- Copy or symlink this repo's `tutorials/` into neu_markdown_buddy at `resources/tutorials/` to browse the same content in the desktop UI\n\nWebsite/cloud usage options:\n\n- Host this PHP app (current repo) on any PHP-capable server or platform (see Installation below)\n- Or serve neu_markdown_buddy's `resources/` (index.html, styles, main.js, libs) as a static site; desktop‑only features (e.g., tray, always‑on‑top, native FS access) won't apply in browsers, but the core reader/navigation work well\n\n## Features\n\n### Core Functionality\n\n- 📚 **Interactive Tutorial Browser** - Navigate through organized tutorial collections\n- 🎨 **Syntax Highlighting** - Code blocks highlighted with Highlight.js for 20+ languages\n- 📱 **Responsive Design** - Works seamlessly on desktop and mobile devices\n- 📋 **Copy to Clipboard** - One-click copying for all code blocks\n- 🧭 **Smart Navigation** - Breadcrumb navigation and expandable folder structure\n- 🔍 **Search \u0026 Discovery** - Sidebar search with live filtering and auto-expanding results\n- 🧩 **Auto-Display Table of Contents** - TOC automatically appears for all tutorials with dynamic toggle functionality\n- 🧱 **Sidebar Width Toggle** - Expand/collapse the sidebar for focus or overview\n- 🎯 **Smooth Scrolling** - In-page anchor navigation with smooth scrolling and target highlight\n- 🧰 **Top Toolbar** - Home, Collapse/Expand All, Refresh, Theme, and Zoom controls\n- 🌗 **Theme Toggle** - Light/Dark theme with instant switch and saved preference\n- 🔎 **Zoom Controls** - 80–180% zoom with live indicator and persistence\n- 💾 **Persistent UI State** - Remembers theme, zoom level, sidebar width, and folder open/closed states\n- 🧮 **Homepage Insights** - Stats (total tutorials, categories, last updated), browse-by-category, and recently added list\n- 🎲 **Random Tutorial** - Jump to a randomly selected guide from the homepage\n- 🖼️ **SVG Favicon + Theme Color** - Crisp tab icon and browser UI color via `\u003clink rel=\"icon\"\u003e` and `meta theme-color`\n\n## Screenshots\n\n### Application Interface\n\n![Main Interface](screenshots/1.png)\n*Main tutorial browser interface with navigation sidebar and content area*\n\n![Tutorial View](screenshots/2.png)\n*Detailed tutorial view with syntax highlighting and copy functionality*\n\n## New Layout: Right‑rail Table of Contents\n\nThe tutorial view uses a two-column article layout:\n\n- Content on the left, a Table of Contents (ToC) on the right.\n- The ToC is sticky (always visible) as you scroll, with smooth scrolling and active section highlighting (scrollspy).\n- The ToC visibility is persisted; use the “Contents” button to show/hide it per your preference.\n- On smaller screens, the ToC appears above the content and remains sticky at the top as you scroll.\n\nReading experience improvements:\n\n- Wider content column designed to avoid wrapping long code lines and to keep copy buttons visible.\n- Increased gap between content and ToC to prevent overlap and create a uniform layout.\n- Zoom now applies only to the article (markdown content), not the ToC. This keeps the ToC fixed and readable while you scale the content.\n\nNotes:\n\n- If a tutorial has very few headings, the ToC will be minimal. You can still hide it via the “Contents” button.\n- Anchor navigation uses stable, GitHub-like heading IDs with smooth scrolling and a brief highlight on the target heading.\n\n## Tutorial Categories\n\n### 📦 Homebrew\n\nComprehensive guides for macOS package management:\n\n- **CLI Tools**: bat, curl, fd-find, gawk, grep, jq, sed, wget\n- **Development Tools**: Docker, FFmpeg, Git, ImageMagick, Ollama, OpenSSL\n- **Programming Languages**: V Language\n- **Security Tools**: Metasploit, Nmap\n- **System Guides**: Keyboard shortcuts, MacBook tips, Terminal usage\n\n### 🐍 Python Standard Library\n\nComplete documentation for Python's built-in modules organized by category:\n\n- Binary Data Services\n- Concurrent Execution\n- Cryptographic Services\n- Data Compression and Archiving\n- File and Directory Access\n- Internet Protocols and Support\n- And many more...\n\n### 📝 Google Apps Script\n\nTutorials for automating Google services:\n\n- Gmail Functions\n- Google Docs automation\n- Google Drive operations\n- Google Sheets manipulation\n- YouTube API integration\n\n## Technology Stack\n\n### Backend\n\n- **PHP 7.4+** - Server-side rendering and routing\n- **Parsedown** - Markdown parsing library\n- **Composer** - Dependency management\n\n### Frontend\n\n- **Pure CSS** - Custom responsive styling\n- **Highlight.js** - Syntax highlighting for 20+ languages\n- **Marked.js** - Client-side markdown processing\n- **Font Awesome** - Icons and visual elements\n\n### Supported Languages\n\n- Python, Java, PHP, JavaScript\n- Bash, SQL, JSON, YAML\n- Docker, Go, Rust, Swift, Kotlin\n- And many more...\n\n## Installation\n\n### Prerequisites\n\n- PHP 7.4 or higher\n- Composer (for dependency management)\n- Web server (built-in PHP server works fine for development)\n\n### Setup\n\n1. **Clone the repository**:\n\n   ```bash\n   git clone https://github.com/codecaine-zz/markdown_tutorials.git\n   cd markdown_tutorials\n   ```\n\n2. **Install dependencies**:\n\n   ```bash\n   composer install\n   ```\n\n3. **Start the development server**:\n\n   ```bash\n   php -S localhost:8080\n   ```\n\n4. **Open in browser**:\n   Navigate to `http://localhost:8080`\n\n## Run as a Desktop App (NeutralinoJS)\n\nYou can package and run this PHP app in a native desktop window using NeutralinoJS. Two simple options are below.\n\n### Option A — Quick connect to your running PHP server (recommended)\n\nPrerequisites:\n\n- Node.js (or Bun) and the NeutralinoJS CLI: `npm i -g @neutralinojs/neu` (or `bun add -g @neutralinojs/neu`)\n\nSteps:\n\n1. Start the PHP server in this repo (choose a port):\n\n```bash\nphp -S 127.0.0.1:8080\n```\n\n1. In a separate folder (e.g., `desktop/`), create a Neutralino app and point the window to your local URL:\n\n```bash\nneu create markdown_tutorials_desktop\ncd markdown_tutorials_desktop\n```\n\n1. Edit `neutralino.config.json` to load the PHP app URL. For recent Neutralino versions, set it under the window mode:\n\n```json\n{\n   \"applicationId\": \"com.markdown.tutorials\",\n   \"defaultMode\": \"window\",\n   \"modes\": {\n      \"window\": {\n         \"title\": \"Markdown Tutorials\",\n         \"width\": 1200,\n         \"height\": 800,\n         \"resizable\": true,\n         \"url\": \"http://127.0.0.1:8080/\"\n      }\n   },\n   \"nativeAllowList\": [\"app.*\", \"window.*\"]\n}\n```\n\nNote: Some Neutralino templates use a top-level `url` instead of `modes.window.url`. If so, set `\"url\": \"http://127.0.0.1:8080/\"` at the top level.\n\n1. Run the desktop app:\n\n```bash\nneu run\n```\n\n1. Build distributables (optional):\n\n```bash\nneu build --release\n```\n\n### Option B — Auto‑start the PHP server from Neutralino (advanced)\n\nYou can have Neutralino start/stop the PHP server when the app launches/exits.\n\n1. In your Neutralino project, allow OS process APIs in `neutralino.config.json`:\n\n```json\n{\n   \"nativeAllowList\": [\n      \"app.*\",\n      \"events.*\",\n      \"window.*\",\n      \"os.spawnProcess\",\n      \"os.updateProcess\",\n      \"os.killProcess\"\n   ]\n}\n```\n\n1. In `resources/js/main.js` (or your app’s entry script), spawn PHP on startup and kill it on exit. Adjust `projectDir` to this repo’s absolute path and `port` if needed:\n\n```javascript\nlet phpPid = null;\nconst port = 8080;\nconst projectDir = \"/absolute/path/to/markdown_tutorials\"; // change this\n\nasync function startPhp() {\n   // php -S 127.0.0.1:8080 -t /path/to/docroot\n   const result = await Neutralino.os.spawnProcess('php', ['-S', `127.0.0.1:${port}`, '-t', projectDir]);\n   phpPid = result.id || result.pid;\n}\n\nasync function stopPhp() {\n   if (phpPid) {\n      try { await Neutralino.os.killProcess(phpPid); } catch (_) {}\n   }\n}\n\nNeutralino.events.on('ready', async () =\u003e {\n   await startPhp();\n   await Neutralino.window.setTitle('Markdown Tutorials');\n   // Ensure your config points the window to http://127.0.0.1:8080\n});\n\nNeutralino.events.on('windowClose', async () =\u003e {\n   await stopPhp();\n   await Neutralino.app.exit();\n});\n```\n\n1. Point the Neutralino window to `http://127.0.0.1:8080/` as in Option A. Then `neu run` will boot PHP and open the desktop window automatically.\n\nIf you prefer a ready‑made desktop wrapper with extra features, see: [codecaine-zz/neu_markdown_buddy](https://github.com/codecaine-zz/neu_markdown_buddy).\n\n## Usage\n\n### Adding New Tutorials\n\n1. Create markdown files (`.md`) in the `tutorials/` directory\n2. Organize them in folders for better navigation\n3. Use standard markdown syntax with front matter if needed\n4. Code blocks will automatically get syntax highlighting and copy buttons\n\nExample tutorial structure:\n\n```text\ntutorials/\n├── category-name/\n│   ├── tutorial-1.md\n│   ├── tutorial-2.md\n│   └── subcategory/\n│       └── advanced-tutorial.md\n```\n\n### Markdown Format\n\nTutorials support standard markdown with enhancements:\n\n````markdown\n# Tutorial Title\n\n## Section Header\n\nRegular text content with **bold** and *italic* formatting.\n\n### Code Examples\n\n```python\ndef hello_world():\n    print(\"Hello, World!\")\n    return True\n```\n\n- Lists work normally\n- With nested items\n  - Like this\n\n\u003e Blockquotes for important notes\n````\n\n## Project Structure\n\n```text\nmarkdown_tutorials/\n├── favicon.svg              # SVG site favicon\n├── index.php                 # Main application entry point\n├── assets/\n│   ├── css/\n│   │   └── style.css         # All application styles\n│   └── js/\n│       └── app.js            # Frontend functionality\n├── logs/                     # Application logs\n├── screenshots/              # Documentation images\n├── tutorials/                # Tutorial content\n│   ├── homebrew/            # Homebrew package guides\n│   ├── python/              # Python documentation\n│   └── google scripts/      # Google Apps Script tutorials\n├── vendor/                   # Composer dependencies\n│   └── parsedown/           # Markdown parser\n└── README.md                # This file\n```\n\n## Homepage Overview\n\nThe homepage now helps you get to content faster:\n\n- Stats summary: total tutorials, total categories, and the time since the latest update\n- Quick actions: focus the sidebar search and open a random tutorial\n- Browse by category: top-level folders with tutorial counts\n- Recently added: most recently updated tutorials with \"time ago\" labels\n\nThese sections are generated dynamically from the `tutorials/` directory.\n\n## Key Features Explained\n\n### Navigation System\n\n- **Hierarchical browsing** with expandable folders\n- **Breadcrumb navigation** shows current location\n- **Mobile-responsive** sidebar with hamburger toggle\n- **Smart expansion** - folders open automatically when viewing contained files\n\n### UI Enhancements\n\n- **Sidebar Width Toggle**\n   - Click the chevron button in the sidebar to expand/collapse it.\n   - The main content shifts to accommodate the chosen width.\n\n- **Sidebar Search (Live Filter)**\n   - Type in the sidebar search box to filter tutorials by name.\n   - Matching items remain visible and parent folders auto-expand for quick access.\n   - Clear the query with the \"×\" button.\n\n- **Toggleable Table of Contents**\n   - Right‑rail ToC (sticky) stays on screen while scrolling.\n   - Click \"Contents\" to show/hide the ToC; your choice is saved across visits.\n   - Generated from page headings with smooth scrolling and active section highlighting.\n   - Target headings briefly highlight when navigated to.\n\n- **Smart \"Previous\" Button Navigation**\n   - When clicking on table of contents links or in-page anchor links, a \"Previous\" button appears next to the target heading.\n   - The button allows you to return to your previous scroll position with one click.\n   - Buttons persist until used (they remove themselves after being clicked) or until you navigate to a different section.\n   - Only one \"Previous\" button is visible at a time - clicking new ToC links replaces the previous button location.\n   - No manual dismiss option keeps the interface clean and focused on core navigation functionality.\n\n- **Enhanced Anchor Navigation**\n   - Stable, GitHub-like heading IDs, smooth in-page links, and automatic link rewrites for reliable anchors.\n\n- **Improved Code Copy UX**\n   - Always-visible copy buttons on code blocks (mobile friendly), with success/failure feedback and clipboard fallback.\n\n- **Top Toolbar**\n   - Quick actions: Home, Collapse All, Expand All, Refresh.\n   - Theme toggle (sun/moon) and Zoom controls with a live percentage indicator.\n   - Zoom scales only the article content; the ToC stays fixed for reliable navigation.\n\n- **Theme \u0026 Zoom Persistence**\n   - Theme and zoom preferences are saved automatically and restored on page load.\n   - Zoom range: 80–180% for comfortable reading.\n\n- **Bulk Sidebar Actions \u0026 Busy Overlay**\n   - Collapse/Expand All folders with a brief, non-blocking spinner overlay.\n   - Keeps the UI responsive during batch updates.\n\n- **Persistent Navigation State**\n   - Remembers sidebar width state (normal/expanded/collapsed).\n   - Restores open/closed states of folders across visits.\n\n- **Keyboard Shortcuts**\n   - F1: Show shortcut help\n   - Ctrl/⌘+F: Find in page (browser)\n   - Ctrl/⌘+K: Focus sidebar search\n   - Cmd/Ctrl+B: Toggle sidebar width\n   - Cmd/Ctrl+H: Home\n   - Plus/Minus: Zoom in/out\n\n#### Searching text (Find in page)\n\n- Find: Ctrl+F (Windows/Linux), ⌘+F (macOS)\n- Find next: F3 or Ctrl+G (Windows/Linux), ⌘+G (macOS)\n- Find previous: Shift+F3 or Ctrl+Shift+G (Windows/Linux), Shift+⌘+G (macOS)\n\n### What's New\n\nLatest updates:\n\n- **Auto-Toggle Table of Contents**: TOC now appears automatically when viewing any markdown tutorial, with improved toggle functionality and dynamic button states\n- New homepage insights panel with quick actions (focus search, random tutorial), stats, browse-by-category, and recently added tutorials\n- Added SVG favicon (`favicon.svg`) and `theme-color` for better browser tab and mobile UI integration\n\nPreviously shipped:\n\n- Top toolbar, dark/light theme toggle, zoom controls with live indicator\n- Batch expand/collapse for the sidebar and persistent UI state (theme, zoom, sidebar width, folder states)\n\n### Syntax Highlighting\n\n- Powered by **Highlight.js 11.9.0**\n- Supports **20+ programming languages**\n   - Includes explicit support for the V language (```v``` code fences) via Highlight.js\n- **GitHub Dark theme** for consistent appearance\n- **Automatic language detection**\n\n### Copy Functionality\n\n- **One-click copying** for all code blocks\n- **Visual feedback** with success/error states\n- **Preserves formatting** and indentation\n\n### Responsive Design\n\n- **Mobile-first approach**\n- **Collapsible sidebar** on small screens\n- **Touch-friendly** navigation elements\n- **Readable typography** across all devices\n\n## Favicon and Theme Color\n\n- Favicon lives at the repo root as `favicon.svg`\n- Included via:\n  - `\u003clink rel=\"icon\" type=\"image/svg+xml\" href=\"/favicon.svg\"\u003e`\n  - `\u003cmeta name=\"theme-color\" content=\"#0f172a\"\u003e`\n\nModern browsers will show the SVG in the tab bar and use the theme color for UI accents (especially on mobile).\n\n## Development\n\n### File Organization\n\n- **Single-file application** (`index.php`) for simplicity\n- **Separation of concerns** with dedicated CSS and JS files\n- **Class-based architecture** with clean method separation and new features\n- **Error handling** with logging to `logs/` directory\n- **Modular JavaScript** with feature-specific functions and improved code organization\n\n### Performance Optimizations\n\n- **Debounced search** to prevent excessive queries\n- **Efficient local storage** usage for user data\n- **Smooth animations** optimized for performance\n- **Lazy loading** for better initial page load\n- **Mobile-first responsive** design with optimized touch interactions\n\n### Adding Language Support\n\nTo add syntax highlighting for additional languages:\n\n1. Add the language script in `index.php`:\n\n   ```php\n   \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/language-name.min.js\"\u003e\u003c/script\u003e\n   ```\n\n2. The highlighting will work automatically in code blocks:\n\n   ````markdown\n   ```language-name\n   // Your code here\n   ```\n   ````\n\n## Troubleshooting\n\n### Common Issues\n\n**Server not starting:**\n- Ensure you're running from the project\n**Styling issues:**\n\n- Clear browser cache\n- Check that `assets/` directory is accessible\n- Verify CSS file loads in browser developer tools\n\n## License\n\nThis project is open source. Feel free to use, modify, and distribute according to your needs.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## Support\n\nFor issues or questions:\n\n- Check the browser console for JavaScript errors\n- Review PHP error logs in `logs/php_errors.log`\n- Verify file permissions and server configuration\n- **Class-based architecture** with clean method separation and new features\n- **Error handling** with logging to `logs/` directory\n- **Modular JavaScript** with feature-specific functions and improved code organization\n\n### Performance Optimizations\n\n- **Debounced search** to prevent excessive queries\n- **Efficient local storage** usage for user data\n- **Smooth animations** optimized for performance\n- **Lazy loading** for better initial page load\n- **Mobile-first responsive** design with optimized touch interactions\n\n### Adding Language Support\n\nTo add syntax highlighting for additional languages:\n\n1. Add the language script in `index.php`:\n\n   ```php\n   \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/language-name.min.js\"\u003e\u003c/script\u003e\n   ```\n\n2. The highlighting will work automatically in code blocks:\n\n   ````markdown\n   ```language-name\n   // Your code here\n   ```\n   ````\n\n## Troubleshooting\n\n### Common Issues\n\n**Server not starting:**\n- Ensure you're running from the project root directory\n- Check PHP version: `php --version`\n- Try a different port: `php -S localhost:3000`\n\n**Tutorials not loading:**\n- Check file permissions on `tutorials/` directory\n- Verify markdown files have `.md` extension\n- Check browser console for JavaScript errors\n\n**Styling issues:**\n- Clear browser cache and local storage\n- Check that `assets/` directory is accessible\n- Verify CSS file loads in browser developer tools\n\n**Features not working:**\n- Ensure JavaScript is enabled in browser\n- Check browser console for errors\n- Verify local storage is available and not full\n- Try clearing local storage data for fresh start\n\n## Browser Compatibility\n\n- **Modern browsers**: Full feature support (Chrome, Firefox, Safari, Edge)\n- **Older browsers**: Graceful degradation with core functionality\n- **Mobile browsers**: Optimized touch interactions and responsive design\n- **Accessibility**: Screen reader support and keyboard navigation\n\n## Performance\n\n- **Fast initial load**: Optimized asset loading and minimal dependencies\n- **Responsive interactions**: Debounced search and smooth animations\n- **Efficient storage**: Smart use of local storage for user data\n- **Mobile optimized**: Touch-friendly interface with optimized touch targets\n\n## License\n\nThis project is open source. Feel free to use, modify, and distribute according to your needs.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly across different browsers and devices\n5. Submit a pull request\n\n## Support\n\nFor issues or questions:\n\n- Check the browser console for JavaScript errors\n- Review PHP error logs in `logs/php_errors.log`\n- Verify file permissions and server configuration\n- Test with local storage cleared for fresh start\n- Check browser compatibility and JavaScript supportable of Contents**\n  - On any tutorial page, click \"Contents\" to show/hide the ToC.\n  - The ToC is generated from headings and supports smooth scrolling.\n  - Target headings briefly highlight when navigated to.\n\n- **Smart \"Previous\" Button Navigation**\n  - When clicking on table of contents links or in-page anchor links, a \"Previous\" button appears next to the target heading.\n  - The button allows you to return to your previous scroll position with one click.\n  - Buttons persist until used (they remove themselves after being clicked) or until you navigate to a different section.\n  - Only one \"Previous\" button is visible at a time - clicking new ToC links replaces the previous button location.\n  - No manual dismiss option keeps the interface clean and focused on core navigation functionality.\n\n- **Enhanced Anchor Navigation**e of Contents**\n   - On any tutorial page, click \"Contents\" to show/hide the ToC.\n   - The ToC is generated from headings and supports smooth scrolling.\n   - Target headings briefly highlight when navigated to.\n\n- **Smart \"Previous\" Button Navigation**\n   - When clicking on table of contents links or in-page anchor links, a \"Previous\" button appears next to the target heading.\n   - The button allows you to return to your previous scroll position with one click.\n   - Buttons persist until used (they remove themselves after being clicked) or until you navigate to a different section.\n   - Only one \"Previous\" button is visible at a time - clicking new ToC links replaces the previous button location.\n   - No manual dismiss option keeps the interface clean and focused on core navigation functionality.\n\n- **Enhanced Anchor Navigation**\n   - Stable, GitHub-like heading IDs, smooth in-page links, and automatic link rewrites for reliable anchors.ience, check out neu_markdown_buddy — a cross‑platform NeutralinoJS port of this project for macOS, Windows, and Linux.\n\n- Repository: [codecaine-zz/neu_markdown_buddy](https://github.com/codecaine-zz/neu_markdown_buddy)\n- Platforms: macOS, Windows, Linux (desktop); core UI also runs in a regular browser\n- Highlights: advanced navigation, smart search, ToC, code copy, theme + zoom, random tutorial, and persistent UI state\n\nQuick desktop start (summary):\n\n- Install Node.js or Bun and the NeutralinoJS CLI (@neutralinojs/neu)\n- In the neu_markdown_buddy repo: run `neu update`, then `neu run` for dev or `neu build` for distributable binaries\n\nUse your existing tutorials with the desktop app:\n\n- Copy or symlink this repo’s `tutorials/` into neu_markdown_buddy at `resources/tutorials/` to browse the same content in the desktop UI\n\nWebsite/cloud usage options:\n\n- Host this PHP app (current repo) on any PHP-capable server or platform (see Installation below)\n- Or serve neu_markdown_buddy’s `resources/` (index.html, styles, main.js, libs) as a static site; desktop‑only features (e.g., tray, always‑on‑top, native FS access) won’t apply in browsers, but the core reader/navigation work well\n\n## Features\n\n- 📚 **Interactive Tutorial Browser** - Navigate through organized tutorial collections\n- 🎨 **Syntax Highlighting** - Code blocks highlighted with Highlight.js for 20+ languages\n- 📱 **Responsive Design** - Works seamlessly on desktop and mobile devices\n- 📋 **Copy to Clipboard** - One-click copying for all code blocks\n- 🧭 **Smart Navigation** - Breadcrumb navigation and expandable folder structure\n- 🔍 **Search \u0026 Discovery** - Sidebar search with live filtering and auto-expanding results\n- 🧩 **Auto-Display Table of Contents** - TOC automatically appears for all tutorials with dynamic toggle functionality\n- 🧱 **Sidebar Width Toggle** - Expand/collapse the sidebar for focus or overview\n- 🎯 **Smooth Scrolling** - In-page anchor navigation with smooth scrolling and target highlight\n- 🧰 **Top Toolbar** - Home, Collapse/Expand All, Refresh, Theme, and Zoom controls\n- 🌗 **Theme Toggle** - Light/Dark theme with instant switch and saved preference\n- 🔎 **Zoom Controls** - 80–180% zoom with live indicator and persistence\n- 💾 **Persistent UI State** - Remembers theme, zoom level, sidebar width, and folder open/closed states\n- 🧮 **Homepage Insights** - Stats (total tutorials, categories, last updated), browse-by-category, and recently added list\n- 🎲 **Random Tutorial** - Jump to a randomly selected guide from the homepage\n- 🖼️ **SVG Favicon + Theme Color** - Crisp tab icon and browser UI color via `\u003clink rel=\"icon\"\u003e` and `meta theme-color`\n\n## Screenshots\n\n### Application Interface\n\n![Main Interface](screenshots/1.png)\n*Main tutorial browser interface with navigation sidebar and content area*\n\n![Tutorial View](screenshots/2.png)\n*Detailed tutorial view with syntax highlighting and copy functionality*\n\n## Tutorial Categories\n\n### 📦 Homebrew\n\nComprehensive guides for macOS package management:\n\n- **CLI Tools**: bat, curl, fd-find, gawk, grep, jq, sed, wget\n- **Development Tools**: Docker, FFmpeg, Git, ImageMagick, Ollama, OpenSSL\n- **Programming Languages**: V Language\n- **Security Tools**: Metasploit, Nmap\n- **System Guides**: Keyboard shortcuts, MacBook tips, Terminal usage\n\n### 🐍 Python Standard Library\n\nComplete documentation for Python's built-in modules organized by category:\n\n- Binary Data Services\n- Concurrent Execution\n- Cryptographic Services\n- Data Compression and Archiving\n- File and Directory Access\n- Internet Protocols and Support\n- And many more...\n\n### 📝 Google Apps Script\n\nTutorials for automating Google services:\n\n- Gmail Functions\n- Google Docs automation\n- Google Drive operations\n- Google Sheets manipulation\n- YouTube API integration\n\n## Technology Stack\n\n### Backend\n\n- **PHP 7.4+** - Server-side rendering and routing\n- **Parsedown** - Markdown parsing library\n- **Composer** - Dependency management\n\n### Frontend\n\n- **Pure CSS** - Custom responsive styling\n- **Highlight.js** - Syntax highlighting for 20+ languages\n- **Marked.js** - Client-side markdown processing\n- **Font Awesome** - Icons and visual elements\n\n### Supported Languages\n\n- Python, Java, PHP, JavaScript\n- Bash, SQL, JSON, YAML\n- Docker, Go, Rust, Swift, Kotlin\n- And many more...\n\n## Installation\n\n### Prerequisites\n\n- PHP 7.4 or higher\n- Composer (for dependency management)\n- Web server (built-in PHP server works fine for development)\n\n### Setup\n\n1. **Clone the repository**:\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd markdown_tutorials\n   ```\n\n2. **Install dependencies**:\n\n   ```bash\n   composer install\n   ```\n\n3. **Start the development server**:\n\n   ```bash\n   php -S localhost:8080\n   ```\n\n4. **Open in browser**:\n   Navigate to `http://localhost:8080`\n\n## Usage\n\n### Adding New Tutorials\n\n1. Create markdown files (`.md`) in the `tutorials/` directory\n2. Organize them in folders for better navigation\n3. Use standard markdown syntax with front matter if needed\n4. Code blocks will automatically get syntax highlighting and copy buttons\n\nExample tutorial structure:\n\n```text\ntutorials/\n├── category-name/\n│   ├── tutorial-1.md\n│   ├── tutorial-2.md\n│   └── subcategory/\n│       └── advanced-tutorial.md\n```\n\n### Markdown Format\n\nTutorials support standard markdown with enhancements:\n\n````markdown\n# Tutorial Title\n\n## Section Header\n\nRegular text content with **bold** and *italic* formatting.\n\n### Code Examples\n\n```python\ndef hello_world():\n    print(\"Hello, World!\")\n    return True\n```\n\n- Lists work normally\n- With nested items\n  - Like this\n\n\u003e Blockquotes for important notes\n````\n\n## Project Structure\n\n```text\nmarkdown_tutorials/\n├── favicon.svg              # SVG site favicon\n├── index.php                 # Main application entry point\n├── assets/\n│   ├── css/\n│   │   └── style.css         # All application styles\n│   └── js/\n│       └── app.js            # Frontend functionality\n├── logs/                     # Application logs\n├── screenshots/              # Documentation images\n├── tutorials/                # Tutorial content\n│   ├── homebrew/            # Homebrew package guides\n│   ├── python/              # Python documentation\n│   └── google scripts/      # Google Apps Script tutorials\n├── vendor/                   # Composer dependencies\n│   └── parsedown/           # Markdown parser\n└── README.md                # This file\n```\n\n## Homepage Overview\n\nThe homepage now helps you get to content faster:\n\n- Stats summary: total tutorials, total categories, and the time since the latest update\n- Quick actions: focus the sidebar search and open a random tutorial\n- Browse by category: top-level folders with tutorial counts\n- Recently added: most recently updated tutorials with “time ago” labels\n\nThese sections are generated dynamically from the `tutorials/` directory.\n\n## Key Features Explained\n\n### Navigation System\n\n- **Hierarchical browsing** with expandable folders\n- **Breadcrumb navigation** shows current location\n- **Mobile-responsive** sidebar with hamburger toggle\n- **Smart expansion** - folders open automatically when viewing contained files\n\n### UI Enhancements\n\n- **Sidebar Width Toggle**\n   - Click the chevron button in the sidebar to expand/collapse it.\n   - The main content shifts to accommodate the chosen width.\n\n- **Sidebar Search (Live Filter)**\n   - Type in the sidebar search box to filter tutorials by name.\n   - Matching items remain visible and parent folders auto-expand for quick access.\n   - Clear the query with the “×” button.\n\n- **Toggleable Table of Contents**\n   - On any tutorial page, click “Contents” to show/hide the ToC.\n   - The ToC is generated from headings and supports smooth scrolling.\n   - Target headings briefly highlight; a small inline “Previous” button returns to your prior scroll position.\n\n- **Enhanced Anchor Navigation**\n   - Stable, GitHub-like heading IDs, smooth in-page links, and automatic link rewrites for reliable anchors.\n\n- **Improved Code Copy UX**\n   - Always-visible copy buttons on code blocks (mobile friendly), with success/failure feedback and clipboard fallback.\n\n- **Top Toolbar**\n   - Quick actions: Home, Collapse All, Expand All, Refresh.\n   - Theme toggle (sun/moon) and Zoom controls with a live percentage indicator.\n\n- **Theme \u0026 Zoom Persistence**\n   - Theme and zoom preferences are saved automatically and restored on page load.\n   - Zoom range: 80–180% for comfortable reading.\n\n- **Bulk Sidebar Actions \u0026 Busy Overlay**\n   - Collapse/Expand All folders with a brief, non-blocking spinner overlay.\n   - Keeps the UI responsive during batch updates.\n\n- **Persistent Navigation State**\n   - Remembers sidebar width state (normal/expanded/collapsed).\n   - Restores open/closed states of folders across visits.\n\n- **Keyboard Shortcuts**\n   - F1: Show shortcut help\n   - Ctrl/⌘+F: Find in page (browser)\n   - Ctrl/⌘+K: Focus sidebar search\n   - Cmd/Ctrl+B: Toggle sidebar width\n   - Cmd/Ctrl+H: Home\n   - Plus/Minus: Zoom in/out\n\n#### Searching text (Find in page)\n\n- Find: Ctrl+F (Windows/Linux), ⌘+F (macOS)\n- Find next: F3 or Ctrl+G (Windows/Linux), ⌘+G (macOS)\n- Find previous: Shift+F3 or Ctrl+Shift+G (Windows/Linux), Shift+⌘+G (macOS)\n\n### What’s New\n\nLatest updates:\n\n- **Auto-Toggle Table of Contents**: TOC now appears automatically when viewing any markdown tutorial, with improved toggle functionality and dynamic button states\n- New homepage insights panel with quick actions (focus search, random tutorial), stats, browse-by-category, and recently added tutorials\n- Added SVG favicon (`favicon.svg`) and `theme-color` for better browser tab and mobile UI integration\n\nPreviously shipped:\n\n- Top toolbar, dark/light theme toggle, zoom controls with live indicator\n- Batch expand/collapse for the sidebar and persistent UI state (theme, zoom, sidebar width, folder states)\n\n### Syntax Highlighting\n\n- Powered by **Highlight.js 11.9.0**\n- Supports **20+ programming languages**\n- **GitHub Dark theme** for consistent appearance\n- **Automatic language detection**\n\n### Copy Functionality\n\n- **One-click copying** for all code blocks\n- **Visual feedback** with success/error states\n- **Preserves formatting** and indentation\n\n### Responsive Design\n\n- **Mobile-first approach**\n- **Collapsible sidebar** on small screens\n- **Touch-friendly** navigation elements\n- **Readable typography** across all devices\n\n## Favicon and Theme Color\n\n- Favicon lives at the repo root as `favicon.svg`\n- Included via:\n  - `\u003clink rel=\"icon\" type=\"image/svg+xml\" href=\"/favicon.svg\"\u003e`\n  - `\u003cmeta name=\"theme-color\" content=\"#0f172a\"\u003e`\n\nModern browsers will show the SVG in the tab bar and use the theme color for UI accents (especially on mobile).\n\n## Development\n\n### File Organization\n\n- **Single-file application** (`index.php`) for simplicity\n- **Separation of concerns** with dedicated CSS and JS files\n- **Class-based architecture** with clean method separation\n- **Error handling** with logging to `logs/` directory\n\n### Adding Language Support\n\nTo add syntax highlighting for additional languages:\n\n1. Add the language script in `index.php`:\n\n   ```php\n   \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/language-name.min.js\"\u003e\u003c/script\u003e\n   ```\n\n2. The highlighting will work automatically in code blocks:\n\n   ````markdown\n   ```language-name\n   // Your code here\n   ```\n   ````\n\n## Troubleshooting\n\n### Common Issues\n\n**Server not starting:**\n\n- Ensure you're running from the project root directory\n- Check PHP version: `php --version`\n- Try a different port: `php -S localhost:3000`\n\n**Tutorials not loading:**\n\n- Check file permissions on `tutorials/` directory\n- Verify markdown files have `.md` extension\n- Check browser console for JavaScript errors\n\n**Styling issues:**\n\n- Clear browser cache\n- Check that `assets/` directory is accessible\n- Verify CSS file loads in browser developer tools\n\n## License\n\nThis project is open source. Feel free to use, modify, and distribute according to your needs.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## Support\n\nFor issues or questions:\n\n- Check the browser console for JavaScript errors\n- Review PHP error logs in `logs/php_errors.log`\n- Verify file permissions and server configuration\n\n## Bun-based installers for persistent Docker containers\n\nIf the Bash installers give you trouble, you can use Bun scripts that perform the same steps, with a friendlier UX:\n\n- `scripts/install-kali-docker-persistent.ts` — sets up a persistent Kali container\n- `scripts/install-ubuntu-docker-persistent.ts` — sets up a persistent Ubuntu container\n\nPrerequisites:\n\n- Bun installed (see \u003chttps://bun.sh\u003e). On macOS with Homebrew: `brew install oven-sh/bun/bun`.\n\nRun them:\n\n```bash\n# Dry-run: list external volumes and exit\nDRY_RUN=1 bun run scripts/install-kali-docker-persistent.ts\n\n# Full run: interactive selection of /Volumes mount, installs Docker if needed\nbun run scripts/install-kali-docker-persistent.ts\n\n# Ubuntu variant\nbun run scripts/install-ubuntu-docker-persistent.ts\n```\n\nYou can also specify a custom base directory instead of selecting an external `/Volumes` drive:\n\n```bash\n# Use your home folder as the base (creates ~/kali-data or ~/ubuntu-data)\nbun run scripts/install-kali-docker-persistent.ts --path \"$HOME\"\nbun run scripts/install-ubuntu-docker-persistent.ts --path \"$HOME\"\n```\n\nNotes:\n\n- Both scripts detect external drives under `/Volumes`, create a `kali-data` or `ubuntu-data` folder for persistence, and bind-mount it at `/data` in the container.\n- If Docker Desktop isn't running, the scripts will automatically start it and wait for the daemon to be ready (60s timeout).\n- If a container named `kali` or `ubuntu` already exists, the script reuses it (`docker start -ai`).\n- On first run, the following languages are automatically installed:\n  - **Python 3** (latest) with pip and venv\n  - **Node.js** (latest LTS)\n  - **Bun** (latest)\n  - **V language** (latest from GitHub)\n\n### Shortcut package scripts\n\nAlternatively, use the bundled package scripts (requires Bun):\n\n```bash\n# Kali\nbun run kali:dry\nbun run kali:install\n\n# Ubuntu\nbun run ubuntu:dry\nbun run ubuntu:install\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodecaine-zz%2Fmarkdown_tutorials","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodecaine-zz%2Fmarkdown_tutorials","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodecaine-zz%2Fmarkdown_tutorials/lists"}