👻 Ghost Recipes
Collaborative code documentation without touching your source files
Add invisible documentation notes to your code. Ghost Recipes stores "phantom recipes" externally in a JSON file, perfect for collaborative technical documentation without modifying your source code.
Features
📝 Invisible Documentation System
Document your code without adding comments to your files. All notes are stored in ghost-recipes.json and can be shared via Git.
Key capabilities:
- Non-invasive: Zero modifications to your source code
- Title + Description: Document functions, variables, classes with structured information
- Smart tracking: Fuzzy search keeps notes synced even when you add/remove lines above
🎨 Visual Interface
- Gutter icons: Discrete ghost indicators next to line numbers
- Rich hover tooltips: Complete information on mouse over
- Sidebar panel: Tree view organized by files
- Toggle visibility: Show/hide notes with one click
📊 Professional PDF Export
Generate executive-style documentation with a single click.
The exported PDF includes:
- Custom cover page with your filename
- Hierarchical numbered index with page references (1.1, 1.2, etc.)
- Content organized by files
- Professional recipe cards with borders
- Project statistics (files, collaborators, recipes)
🌍 Multi-language Support
Automatically adapts to your VS Code language setting:
🤝 Team Collaboration
![Sidebar panel]
- Version control ready:
ghost-recipes.json is designed to be committed
- Multi-user tracking: Each recipe records author and timestamp
- Git history: Track documentation evolution alongside code changes
Getting Started
📖 Quick Start Guide
Adding Your First Recipe
- Right-click on any line in your code
- Select "Add Ghost Recipe" from the context menu
- Enter a title (e.g.,
calculateTotal(), API_KEY)
- Add your documentation (purpose, parameters, return values, etc.)
- Done! 👻
Viewing Your Recipes
- Hover: Move your mouse over the ghost icon
- Sidebar: Click the Ghost Recipes icon in the activity bar
- Quick Pick:
Ctrl+Shift+P → "Ghost Recipes: List All Notes"
Toggle Visibility
Click the eye icon in the status bar (bottom-left) or use:
Ctrl+Shift+P → "Ghost Recipes: Toggle Visibility"
⌨️ Commands & Shortcuts
All available commands:
Command
Shortcut
Description
Ghost Recipes: Add Recipe
Right-click menu
Add note at current line
Ghost Recipes: List All Notes
Command Palette
View and manage all recipes
Ghost Recipes: Toggle Visibility
Status bar icon
Show/hide visualizations
Ghost Recipes: Export to PDF
Sidebar button
Generate PDF documentation
Ghost Recipes: Refresh
Sidebar button
Refresh tree view
📂 Project Structure & JSON Format
File Structure
your-project/
├── ghost-recipes.json # 👻 Your recipes (commit this!)
├── src/│
├── file1.py│
└── file2.js└── README.md
The ghost-recipes.json file stores all your documentation:
{
"recipes": [
{
"path": "src/main.py",
"line": 10,
"title": "calculate_total()",
"comment": "Calculates total by adding taxes and discounts",
"author": "john_doe",
"date": "Dec 30, 2025, 5:05 PM",
"lineContent": "def calculate_total():"
}
]
}
🤝 Team Collaboration Workflow
Initial Setup
Daily Workflow
- Document your code using Ghost Recipes
- Commit and push the
ghost-recipes.json file
- Your team pulls and sees your notes automatically
- Resolve conflicts if needed (same as any JSON file)
Important
DO NOT add ghost-recipes.json to .gitignore - you want to share these notes with your team!
💡 Use Cases & Examples
API Documentation
Title: POST /api/usersDescription: Creates a new user.Requires: email (string), password (string)Returns: { userId: number, token: string }
Algorithm Explanations
Title: quicksort_partition()Description: Divides array using last element as pivot.Complexity: O(n). Used by main quicksort function.Note: Modifies array in-place.
Configuration Notes
Title: DATABASE_URLDescription: Database connection string environment variableFormat: postgresql://user:pass@host:port/dbDevelopment: Use .env fileProduction: Stored in AWS Secrets Manager
Technical Debt Tracking
Title: validate_input()Description: Validates user input for special charactersTODO: Add validation for empty stringsFIXME: Doesn't handle unicode correctlySee: Issue [#123](https://github.com/byroncl/ghost-recipes/issues/123) on GitHub
📄 PDF Export Details
Generated PDF Structure
The exported PDF includes:
1. Cover Page
- Custom filename as title
- Project statistics
- Generation timestamp
2. Table of Contents
- Numbered files (1, 2, 3...)
- Sub-items with recipe titles (1.1, 1.2, 1.3...)
- Page number references
3. Content Sections
- One section per file
- Recipe cards with borders
- Metadata (line number, author, date)
- Hierarchical numbering matching the index
Extension Settings
This extension contributes the following settings:
Currently, Ghost Recipes works out of the box with no configuration needed. Future versions may add customization options.
📋 Requirements
- Visual Studio Code version 1.107.0 or higher
- No additional dependencies required
⚠️ Known Issues
- PDF generation doesn't support clickable internal links (limitation of PDFKit library)
- Very large projects (1000+ recipes) may experience slight performance impact
Report issues on GitHub Issues
🎉 Release Notes
0.0.1
Initial release of Ghost Recipes:
- ✅ Ghost icon indicators in gutter
- ✅ Hover tooltips with full recipe information
- ✅ Sidebar tree view
- ✅ Fuzzy search to track code changes
- ✅ Professional PDF export
- ✅ Multi-language support (EN/ES)
- ✅ Team collaboration via Git
❓ FAQ
Q: Will this modify my code files?
A: No! All documentation is stored in ghost-recipes.json, your source code remains untouched.
Q: Can I use this for any programming language?
A: Yes! Ghost Recipes is language-agnostic and works with any file type.
Q: What happens if I edit code above a recipe?
A: The fuzzy search algorithm automatically tracks the code and updates the line number.
Q: Can I customize the ghost icon?
A: Currently not configurable, but it's on the roadmap for future versions.
Q: How do I share recipes with my team?
A: Simply commit ghost-recipes.json to your Git repository. Your team will see the recipes when they pull.
Contributing
Contributions are welcome! To contribute:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
License
MIT License - see LICENSE file for details
Byron - @Byroncl
Repository: ghost-recipes
Made with 👻 and ❤️ for developers who document!
