Annotations and Tooltips

Annotations provide inline explanations that appear as tooltips when users hover over or focus on technical terms, making your content more accessible and educational.

Basic Syntax

Use ::annotation[text]{explanation} to create a tooltip:

The DOMDocument Object Model is a tree structure.

Common Use Cases

Technical Acronyms

Explain acronyms without interrupting the flow:

Learn HTMLHyperText Markup Language, CSSCascading Style Sheets, and JSJavaScript to build websites.

API Documentation

RESTRepresentational State Transfer APIs use HTTPHyperText Transfer Protocol methods for communication.

Programming Concepts

Understanding MVCModel-View-Controller architecture is essential for web development.

Web Development Terms

Frontend Technologies

React uses a Virtual DOMA lightweight copy of the actual DOM for efficient updates for performance optimization.

The SPASingle Page Application pattern improves user experience by avoiding full page reloads.

Modern frameworks support HMRHot Module Replacement for instant updates during development.

Backend Technologies

GraphQLA query language for APIs that allows clients to request exactly the data they need provides an alternative to REST.

Use JWTJSON Web Token for stateless authentication.

A CDNContent Delivery Network improves load times by serving assets from servers closer to users.

Build Tools

WebpackA module bundler for JavaScript applications handles asset optimization.

BabelA JavaScript compiler that converts modern syntax to older versions ensures browser compatibility.

Database Terminology

Database Concepts

ACIDAtomicity, Consistency, Isolation, Durability properties ensure reliable database transactions.

NoSQLNot Only SQL - databases that don't use traditional relational models databases scale horizontally.

Use ORMObject-Relational Mapping to interact with databases using objects instead of SQL.

Query Optimization

IndexingCreating data structures to speed up data retrieval improves query performance.

Understanding Big OMathematical notation describing algorithm complexity helps optimize queries.

Git and Version Control

Git Basics

Create a PRPull Request to propose changes to a repository.

Use rebaseReapplying commits on top of another base tip to maintain a clean history.

Cherry-pickingApplying specific commits from one branch to another helps backport fixes.

Workflows

The GitFlowA branching model for Git with specific branch purposes workflow organizes development.

Cloud and DevOps

Infrastructure

Deploy applications using IaCInfrastructure as Code tools like Terraform.

CI/CDContinuous Integration and Continuous Deployment automates testing and deployment.

Use K8sKubernetes - an orchestration system for containerized applications to manage containers.

Monitoring

Set up APMApplication Performance Monitoring to track application health.

Configure SLOService Level Objective targets for system reliability.

Security Terms

Authentication and Authorization

Implement OAuthOpen Authorization - a standard for access delegation for secure authentication.

Use 2FATwo-Factor Authentication to enhance security.

RBACRole-Based Access Control manages user permissions efficiently.

Encryption

TLSTransport Layer Security encrypts data in transit.

Store passwords with bcryptA password hashing function designed to be computationally expensive for security.

Algorithmic Concepts

Time Complexity

O(1)Constant time - execution doesn't change with input size operations are most efficient.

O(log n)Logarithmic time - common in binary search algorithms scales well.

O(n)Linear time - execution grows proportionally with input is acceptable for most operations.

Avoid O(n²)Quadratic time - often seen in nested loops algorithms for large datasets.

Data Structures

A heapA tree-based data structure satisfying the heap property enables efficient priority queues.

TrieA tree structure for storing strings with shared prefixes optimizes string searches.

Design Patterns

Creational Patterns

The SingletonEnsures a class has only one instance pattern manages global state.

Use FactoryCreates objects without specifying exact classes for flexible object creation.

Behavioral Patterns

The ObserverMaintains a list of dependents and notifies them of state changes pattern implements event systems.

StrategyDefines a family of algorithms and makes them interchangeable enables runtime algorithm selection.

Network Concepts

Protocols

TCPTransmission Control Protocol - ensures reliable data delivery guarantees packet order.

UDPUser Datagram Protocol - faster but doesn't guarantee delivery suits real-time applications.

WebSocketA protocol for full-duplex communication over a single TCP connection enables real-time features.

Performance

Enable gzipA file compression format for reducing transfer sizes to reduce bandwidth.

Implement cachingStoring copies of data for faster access to improve performance.

Use lazy loadingDeferring resource loading until needed to speed up initial page loads.

In Lists

Create glossaries with annotations:

Web Standards

• W3CWorld Wide Web Consortium - Standards organization
• WHATWGWeb Hypertext Application Technology Working Group - HTML standards
• TC39Technical Committee 39 - JavaScript standards body
• IETFInternet Engineering Task Force - Internet standards

HTTP Status Codes

• 200OK - Request succeeded
• 404Not Found - Resource doesn't exist
• 500Internal Server Error - Server encountered an error

In Tables

Complex Explanations

Annotations can have longer, detailed explanations:

Modern browsers implement Service WorkersJavaScript files that run in the background, separate from web pages, enabling features like offline functionality, push notifications, and background sync without requiring the page to be open.

Best Practices

Use for Unfamiliar Terms

✅ Good:

The REPLRead-Eval-Print Loop is useful for testing.

❌ Avoid:

The functionA reusable block of code performs a task.

(Too common - doesn't need explanation)

Keep Explanations Concise

✅ Good:

APIApplication Programming Interface

❌ Too Verbose:

APIAn Application Programming Interface, which is essentially a set of rules and protocols that allows different software applications to communicate with each other, enabling data exchange and functionality sharing between systems

Explain First Occurrence

✅ Good:

Use JWTJSON Web Token for authentication. Configure JWT expiration times carefully.

❌ Redundant:

Use JWTJSON Web Token for authentication. Configure JWTJSON Web Token expiration carefully.

Accessibility Features

Annotations are built with accessibility in mind:

• Semantic HTML: Uses <abbr> elements
• Title Attribute: Provides native browser tooltips
• Keyboard Navigation: Focusable with Tab key
• ARIA Attributes: Proper role and tabindex
• Screen Reader: Title read aloud by assistive tech
• Print Friendly: Explanations appear in parentheses

Styling

Annotations automatically get:

• Dotted underline in accent color
• Cursor changes to help icon
• Tooltip appears on hover/focus
• Light and dark mode support
• Responsive positioning
• Print-friendly formatting

Interaction

Users can access explanations by:

• Hovering with mouse
• Focusing with keyboard (Tab key)
• Touching on mobile devices
• Reading in print (shows inline)

Syntax Reference

::annotation[text]{explanation}

Examples:

• ::annotation[HTML]{HyperText Markup Language}
• ::annotation[API]{Application Programming Interface}
• ::annotation[DOM]{Document Object Model}

Parameters:

• text - The visible text (required)
• explanation - The tooltip content (required)

Browser Compatibility

Works in all modern browsers:

• Chrome/Edge
• Firefox
• Safari
• Mobile browsers

Fallback: Native title tooltips work everywhere.

Real-World Example

Tutorial with Annotations

When building a RESTRepresentational State Transfer API with Node.jsA JavaScript runtime for server-side development, you'll use ExpressA minimal web framework for Node.js to handle HTTPHyperText Transfer Protocol requests. Configure CORSCross-Origin Resource Sharing to allow requests from your SPASingle Page Application frontend.

For data persistence, connect to a MongoDBA NoSQL document database instance using MongooseAn ODM (Object Data Modeling) library for MongoDB and Node.js. Implement JWTJSON Web Token authentication to secure your endpointsURL paths that accept API requests.

Related Features

• Keyboard Shortcuts - For visual key representation
• Inline Code - For code snippets
• Asides - For longer explanations