Notably 📝

A modern, cross-browser note-taking extension that helps you capture ideas, thoughts, and information on any website.

---

✨ Features

• 📝 Quick Note Taking - Take notes instantly on any website
• 🔗 URL Association - Notes are automatically linked to the current website
• 🏷️ Tag System - Organize notes with custom tags for easy categorization
• 🔍 Search & Filter - Quickly find notes by searching through titles, content, and tags
• 📚 View All Notes - Browse all your saved notes in one place
• 🎨 Theme Customization - Choose from 6 beautiful color themes (Yellow, Pink, Blue, Green, Orange, Purple)
• 📤 Export Functionality - Export all your notes to JSON format
• 📥 Import Functionality - Import notes from previously exported JSON files
• 🗑️ Trash with Restore - Deleted notes go to trash and can be restored (30-day retention, 50-note limit)
• ☁️ Cloud Sync - Automatic synchronization across devices using browser sync storage
• 🌐 Cross-Browser - Works on both Chrome and Firefox
• ⌨️ Keyboard Shortcuts - Quick save and delete with keyboard commands
• 📁 Smart Organization - Notes automatically grouped by website domain
• ⭐ Starred Notes - Mark important notes as favorites for quick access

---

⌨️ Keyboard Shortcuts

Speed up your note-taking workflow with these convenient keyboard shortcuts:

Shortcut	Action	Description
Ctrl+Enter (Mac: Cmd+Enter)	Save Note	Quickly save the current note
Ctrl+Shift+Backspace (Mac: Cmd+Shift+Backspace)	Delete Note	Delete the current note

Tip: Hover over the Save and Delete buttons to see the keyboard shortcuts!

---

📸 Screenshots

Coming soon! Screenshots of the extension in action.

---

🚀 Installation

For Users

Chrome Web Store

Coming soon - Extension will be available on Chrome Web Store

Firefox Add-ons

Coming soon - Extension will be available on Firefox Add-ons

Manual Installation (Development)

Chrome:

1. Download or clone this repository
2. Run npm install and npm run build:chrome
3. Open Chrome and navigate to chrome://extensions/
4. Enable "Developer mode" (toggle in top-right corner)
5. Click "Load unpacked"
6. Select the dist-chrome folder from the project

Firefox:

1. Download or clone this repository
2. Run npm install and npm run build:firefox
3. Open Firefox and navigate to about:debugging#/runtime/this-firefox
4. Click "Load Temporary Add-on"
5. Select the manifest.json file from the dist-firefox folder

---

💻 Development

Prerequisites

• Node.js (v18 or higher)
• npm (v9 or higher)
• Git

Setup

1. Clone the repository

   git clone https://github.com/PMFrancisco/Notably.git
   cd Notably

2. Install dependencies

   npm install

3. Run development server

   npm run dev

4. Build for production

   # Build for both browsers
   npm run build:cross-browser
   
   # Or build for specific browser
   npm run build:chrome    # Chrome/Edge
   npm run build:firefox   # Firefox

Available Scripts

Script	Description
npm run dev	Start development server with HMR
npm run build	Build the extension
npm run build-ts	TypeScript check + build
npm run build:cross-browser	Build for both Chrome and Firefox
npm run build:chrome	Build specifically for Chrome
npm run build:firefox	Build specifically for Firefox
npm run lint	Run ESLint for code quality
npm test	Run Jest tests
npm run preview	Preview production build

---

🛠️ Tech Stack

Frontend:

• React 19.2.0 - UI framework
• TypeScript 5.8.3 - Type safety
• Vite 6.3.6 - Build tool & dev server
• Tailwind CSS 4.1.14 - Styling
• Lucide React - Icons

Browser APIs:

• webextension-polyfill - Cross-browser compatibility

Testing:

• Jest 29.7.0 - Test runner
• React Testing Library - Component testing
• @testing-library/user-event - User interaction testing

Code Quality:

• ESLint 9.37.0 - Linting
• TypeScript ESLint - TypeScript-specific linting rules

---

📁 Project Structure

Notably/
├── .github/
│   └── workflows/          # GitHub Actions CI/CD
├── public/
│   ├── icons/             # Extension icons
│   ├── manifest.json      # Base manifest
│   ├── manifest-chrome.json
│   └── manifest-firefox.json
├── src/
│   ├── components/        # React components (Atomic Design)
│   │   ├── atoms/        # Basic UI elements
│   │   ├── molecules/    # Composite components
│   │   ├── organisms/    # Complex components
│   │   └── templates/    # Page layouts
│   ├── hooks/            # Custom React hooks
│   ├── utils/            # Utility functions
│   ├── types/            # TypeScript type definitions
│   ├── background/       # Background script
│   ├── content/          # Content script
│   ├── __tests__/        # Test files
│   ├── App.tsx           # Main app component
│   └── main.tsx          # Entry point
├── scripts/              # Build scripts
└── jest/                 # Jest configuration

Architecture

The project follows the Atomic Design pattern:

• Atoms: Basic building blocks (Button, Input, Badge, Textarea, etc.)
• Molecules: Simple combinations (FormField, TagInput, SearchBar, ThemeSelector, etc.)
• Organisms: Complex components (NoteForm, NotesList, NoteCard, DomainGroup, etc.)
• Templates: Page layouts (NoteTemplate, NotesListTemplate, etc.)

---

🧪 Testing

Run the test suite:

npm test

Run tests in watch mode:

npm test -- --watch

Run tests with coverage:

npm test -- --coverage

Current Test Coverage:

• ✅ 22 tests passing
• Component rendering
• User interactions
• Form validation
• Note management
• Navigation
• Search functionality

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Write clean, readable code
   • Follow the existing code style
   • Add tests for new features
   • Update documentation as needed

4. Run quality checks

   npm run lint    # Check code quality
   npm test        # Run tests
   npm run build   # Ensure it builds

5. Commit your changes

   git commit -m 'feat: add amazing feature'

   Follow Conventional Commits format

6. Push to your fork

   git push origin feature/amazing-feature

7. Open a Pull Request

Commit Convention

This project uses Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

---

📝 Usage

Taking a Note

1. Click the Notably icon in your browser toolbar
2. The extension popup opens showing the current website
3. Add a title (optional) and your note content
4. Add tags by typing and pressing Enter or comma
5. Click "Save Note" to save

Viewing All Notes

1. Open the extension popup
2. Click "All Notes" button
3. Browse all your saved notes, automatically grouped by website domain
4. Starred notes appear in a special section at the top for quick access
5. Click on any domain name to expand/collapse notes from that site
6. Use the search bar to filter notes (switches to flat list view when searching)
7. Click the delete button to remove notes

Starring Notes

1. Go to "All Notes" view
2. Click the ☆ icon on any note to star it (it becomes ⭐)
3. Starred notes appear in the "⭐ Starred" section at the top
4. Starred notes also remain visible in their domain groups with the ⭐ icon
5. Click the ⭐ icon again to unstar a note

Using Trash

When you delete a note, it's not permanently removed - it goes to trash where you can recover it:

1. Deleting a Note: Click the delete button (🗑️) on any note to move it to trash
2. Accessing Trash: In "All Notes" view, click the 🗑️ icon in the header (shows count of trashed items)
3. Restoring Notes: In trash view, hover over a note and click the ↺ restore button
4. Permanent Deletion: Hover over a note and click the × button to permanently delete it
5. Empty Trash: Click "Empty Trash" button to permanently delete all trashed notes at once
6. Auto-Cleanup: Notes are automatically removed from trash after 30 days
7. Storage Limit: Trash keeps your last 50 deleted notes maximum

Note: Starred status is preserved when notes are moved to trash and restored!

Exporting Notes

1. Go to "All Notes" view
2. Click "Export All Notes" button
3. A JSON file will be downloaded with all your notes

Importing Notes

1. Go to "All Notes" view
2. Click "Import Notes" button
3. Select a previously exported JSON file
4. Your notes will be imported and merged with existing notes
5. Notes with the same URL will be overwritten with the imported version

Changing Themes

1. Look for the colored circle in the top-right corner
2. Click it to reveal the theme selector
3. Choose your preferred color theme
4. The theme is saved automatically

---

🔐 Privacy

• ✅ No data collection - Notably doesn't collect or send any user data
• ✅ Local storage - All notes are stored locally in your browser
• ✅ Browser sync - Optional sync uses your browser's built-in sync (encrypted by your browser)
• ✅ No tracking - No analytics, no tracking, no telemetry
• ✅ Open source - Full transparency - check the code yourself!

Permissions

• storage - To save your notes
• tabs - To get the current tab's URL
• activeTab - To associate notes with websites

---

🗺️ Roadmap

Version 0.4.0 (Completed)

• Search and filter notes
• Import notes from JSON
• Keyboard shortcuts
• Toast notifications

Version 0.5.0 (Current)

• Folders/categories (organized by domain)
• Favorites/starred notes
• Trash with restore functionality

Version 0.6.0+ (Future)

• Smart tagging with autocomplete
• Note templates
• Linked notes
• Enhanced themes
• Browser sidebar support

See CHANGELOG.md for version history.

---

📜 License

This project is licensed under the ISC License. See the LICENSE file for details.

---

👨‍💻 Author

PMFrancisco

• GitHub: @PMFrancisco
• Project: Notably

---

🙏 Acknowledgments

• Built with Vite
• UI components inspired by shadcn/ui
• Icons from Lucide
• Cross-browser compatibility via webextension-polyfill

---

📧 Support

If you encounter any issues or have questions:

• 🐛 Open an issue
• 💬 Start a discussion

---

⭐ Show Your Support

If you find Notably useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🤝 Contributing to the code
• 📢 Sharing with others

---

Made with ❤️ by PMFrancisco

Happy note-taking! 📝