Skip to main content

​
Getting Started

Contributions are welcome! Knowledge Tooltip is designed to be simple and accessible. The entire codebase is vanilla JavaScript with no build tools or dependencies.
Before contributing, make sure you’ve completed the development setup and understand the project structure.

​
Code Standards

​
Vanilla JavaScript Only

This project intentionally avoids frameworks and build tools:
  • Write plain JavaScript (ES6+)
  • No TypeScript, React, Vue, or other frameworks
  • No npm, webpack, or bundlers
  • No transpilation or compilation
Why? To keep the codebase simple, auditable, and accessible to developers of all skill levels.
If you’re used to modern frameworks, this is a great opportunity to practice vanilla JavaScript skills!

​
Code Style

Follow these conventions for consistency: JavaScript:
  • Use const and let (avoid var)
  • Use arrow functions for callbacks
  • Use async/await for promises
  • Use template literals for string interpolation
  • Add comments for complex logic
  • Use semicolons
// Good
const fetchData = async (term) => {
  const response = await fetch(`https://api.example.com?q=${term}`);
  return await response.json();
};

// Avoid
var fetchData = function(term) {
  return fetch('https://api.example.com?q=' + term)
    .then(function(response) {
      return response.json();
    });
};
HTML:
  • Use semantic HTML elements
  • Use kebab-case for IDs and classes
  • Add ARIA attributes for accessibility
CSS:
  • Use CSS custom properties for theming
  • Use meaningful class names
  • Support RTL (right-to-left) layouts for Arabic
  • Avoid !important

​
File Organization

Keep the flat file structure: 
/
├── manifest.json
├── background.js
├── content.js
├── styles.css
├── popup.html
├── popup.js
└── icons/
Do not introduce subdirectories for scripts or modules. Keep all JavaScript files at the root level.

​
Testing Workflow

​
Manual Testing

Before submitting a pull request:
1

Test Core Functionality

  1. Load the extension in Chrome (see setup guide)
  2. Test text selection on multiple websites
  3. Test all five tabs: Summary, Define, Facts, AI, Translate
  4. Test with both English and Arabic content
2

Test Language Modes

  1. Open the extension popup
  2. Test each language setting:
    • Auto-detect
    • English
    • Arabic
  3. Verify UI language switches correctly
  4. Verify API calls use the correct language
3

Test Edge Cases

  • Very long text selections (100+ words)
  • Single-character selections
  • Non-Latin characters (Arabic, Chinese, emoji)
  • Terms with no Wikipedia/Wiktionary results
  • Network errors (test with DevTools offline mode)
4

Test Browser Compatibility

Test on at least two Chromium browsers:
  • Chrome
  • Edge
  • Brave
5

Check Console for Errors

  1. Open DevTools console
  2. Perform various actions
  3. Verify no JavaScript errors appear

​
Testing APIs

Free APIs (no key required):
  • Test Summary with: “Python programming”, “مصر” (Egypt in Arabic)
  • Test Define with: “serendipity”, “ephemeral”
  • Test Facts with: “Paris”, “Albert Einstein”
OpenAI APIs (key required):
  • Test AI with follow-up questions
  • Test Translate with English and Arabic text
  • Verify conversation history works correctly
If you don’t have an OpenAI API key for testing, note that in your pull request. Maintainers will test those features.

​
Areas for Contribution

Here are specific areas where contributions are especially welcome:

​
1. Language Support

Add support for additional languages beyond English and Arabic. What’s needed:
  • UI translations in content.js and popup.html
  • Language detection logic in content.js
  • API calls to language-specific Wikipedia/Wiktionary endpoints
  • RTL support in styles.css if applicable
Example: Adding Spanish support
content.js
// Add Spanish labels to TABS
const TABS = [
  { id: 'summary', label: 'Summary', labelAr: 'ملخص', labelEs: 'Resumen' },
  // ...
];

​
2. New Knowledge Tabs

Add new tabs with additional data sources. Ideas:
  • Synonyms/antonyms tab
  • Images/media tab
  • Related topics tab
  • Etymology tab
  • News articles tab
Requirements:
  • Use free, public APIs (no authentication preferred)
  • Add API domain to host_permissions in manifest.json
  • Implement fetch function in background.js
  • Add tab definition and rendering in content.js
  • Add tab icon SVG

​
3. Improved AI Prompts

Enhance the AI tab prompts for better explanations. Current prompts: See background.js around line 200 Improvements:
  • Better context awareness
  • More concise explanations
  • Age-appropriate explanations (ELI5 mode)
  • Domain-specific prompts (science, history, etc.)

​
4. Accessibility Improvements

What’s needed:
  • ARIA labels for all interactive elements
  • Keyboard navigation support
  • Screen reader testing
  • High contrast mode support
  • Focus indicators
Example: 
<button aria-label="Close tooltip" class="close-btn">
  <span aria-hidden="true">×</span>
</button>

​
5. UI/UX Enhancements

Ideas:
  • Tooltip positioning improvements
  • Better mobile browser support
  • Smooth animations
  • Dark mode support
  • Customizable themes

​
6. Performance Optimizations

Areas:
  • Reduce memory usage
  • Optimize cache invalidation
  • Lazy load tab content
  • Debounce API calls
  • Minimize DOM operations

​
Submitting Changes

​
Before Submitting

​
Pull Request Process

1

Fork and Clone

Fork the repository and clone your fork:
git clone https://github.com/your-username/knowledge-tooltip.git
2

Create a Branch

Create a descriptive branch name:
git checkout -b add-spanish-language
3

Make Changes

Implement your feature or fix following the guidelines above.
4

Test Thoroughly

Follow the testing workflow to verify everything works.
5

Commit Changes

Write clear commit messages:
git add .
git commit -m "Add Spanish language support"
6

Push and Create PR

Push to your fork and create a pull request:
git push origin add-spanish-language
Then open a pull request on GitHub with:
  • Clear description of changes
  • Screenshots/GIFs if UI changes
  • Testing notes (especially if API key required)

​
PR Template

Use this template for your pull request description: 
## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] UI/UX improvement
- [ ] Documentation update
- [ ] Performance optimization

## Testing
- [ ] Tested on Chrome
- [ ] Tested on Edge/Brave
- [ ] Tested English mode
- [ ] Tested Arabic mode
- [ ] All tabs working
- [ ] No console errors

## Screenshots
(If applicable)

## Notes
Any additional context or notes for reviewers.

​
Code Review

Maintainers will review your PR and may:
  • Request changes
  • Ask questions
  • Suggest improvements
  • Merge your contribution
Be responsive to feedback and iterate on your changes.
Small, focused PRs are easier to review and merge than large, multi-feature changes. Consider breaking large changes into multiple PRs.

​
Privacy and Security

Knowledge Tooltip prioritizes user privacy. When contributing:
Never:
  • Add analytics or tracking
  • Send user data to third parties (except necessary API calls)
  • Store sensitive data in chrome.storage.sync
  • Hard-code API keys or secrets
  • Add dependencies that collect telemetry
Always:
  • Store API keys in chrome.storage.local only
  • Make API calls through background.js
  • Minimize data collection
  • Document what data is sent where
  • Update PRIVACY_POLICY.md if data handling changes

​
Questions?

If you have questions or need help:
  1. Check the development setup guide
  2. Review the project structure documentation
  3. Open a GitHub issue with the question label
  4. Tag maintainers in your PR if you need guidance

Development Setup

Get your development environment ready

Project Structure

Understand the codebase architecture
Thank you for contributing to Knowledge Tooltip! Your efforts help make knowledge more accessible to everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us