# How Emojis Adjacent to Markdown Links Are Detected in Developer Portfolios

> Discover how developer portfolios detect emojis adjacent to markdown links. Learn about the Python functions and regex patterns used for identification.

- Repository: [Emma Bostian/developer-portfolios](https://github.com/emmabostian/developer-portfolios)
- Tags: how-to-guide
- Published: 2026-06-01

---

**The detection system uses two specialized functions in [`src/alphabetical.py`](https://github.com/emmabostian/developer-portfolios/blob/main/src/alphabetical.py)—`emoji_adjacent_to_link()` applies regex patterns to find bracketed or parenthesized descriptions following markdown links, then delegates to `has_emoji()` to check for Unicode emoji code points within those descriptions.**

The `emmabostian/developer-portfolios` repository maintains a curated list of developer portfolio examples, requiring robust text processing to handle various markdown formats. Accurate detection of emojis positioned immediately after markdown links enables automated README cleaning and validation workflows according to the repository's source code.

## The Core Detection Architecture

The detection logic resides in [`src/alphabetical.py`](https://github.com/emmabostian/developer-portfolios/blob/main/src/alphabetical.py) and operates through a two-function pipeline designed to parse markdown syntax and analyze Unicode content.

### The has_emoji Helper Function

The `has_emoji(text: str) → bool` function serves as the Unicode verification engine. It iterates over each character in the input string and checks whether the code point falls within predefined emoji ranges stored in `_EMOJI_RANGES`. The function returns `True` immediately upon finding the first qualifying code point, making it efficient for short-circuit evaluation.

According to the source at [`alphabetical.py#L323-L335`](https://github.com/emmabostian/developer-portfolios/blob/master/src/alphabetical.py#L323-L335), the implementation avoids external regex libraries by using direct integer comparisons against Unicode intervals.

### The emoji_adjacent_to_link Orchestrator

The `emoji_adjacent_to_link(markdown_line: str) → bool` function handles the markdown parsing logic. It looks for markdown links formatted as `[text](url)` followed immediately by a description written in either square brackets `[desc]` or parentheses `(desc)`. When such a description is found, the function passes the captured text to `has_emoji()` to determine if an emoji is present.

This implementation spans lines [`alphabetical.py#L352-L372`](https://github.com/emmabostian/developer-portfolios/blob/master/src/alphabetical.py#L352-L372) in the repository.

## Step-by-Step Detection Logic

The `emoji_adjacent_to_link` function processes each line through a strict sequence of validation steps.

### Step 1: Empty Line Validation

The function short-circuits immediately if the input line is empty, returning `False` without further processing.

### Step 2: Bracketed Description Detection

For square-bracketed descriptions, the function applies the regex pattern:

```python
r"\]\s*\([^)]*\)\s*\[([^]]+)\]"

```

This pattern matches the closing bracket `]` of the markdown link, followed by optional whitespace, the URL inside parentheses, more optional whitespace, and finally a new `[desc]` group. The captured group `([^]]+)` contains the description text examined for emojis.

### Step 3: Parenthesized Description Detection

If the bracketed pattern fails, the function checks for parenthesized descriptions using:

```python
r"\]\s*\([^)]*\)\s*\(([^)]+)\)"

```

This similar pattern captures text within parentheses `(desc)` that immediately follow the markdown link structure. The captured group is similarly passed to `has_emoji()` for Unicode verification.

## Unicode-Aware Emoji Recognition

The underlying `has_emoji` implementation performs direct code point analysis against predefined Unicode intervals. As defined at [`alphabetical.py#L301-L319`](https://github.com/emmabostian/developer-portfolios/blob/master/src/alphabetical.py#L301-L319), the `_EMOJI_RANGES` tuple contains intervals such as `0x1F300–0x1F5FF` and `0x2600–0x26FF`.

This approach makes the detection independent of external emoji libraries and ensures consistent behavior across different Python environments. The `_is_emoji_codepoint` helper checks if a given integer falls within any of these ranges.

## Practical Implementation Examples

The following examples demonstrate the detection behavior for various markdown patterns:

```python
from src.alphabetical import emoji_adjacent_to_link

# ✅ Detected – bracketed description containing an emoji

line1 = "- [Demo](https://example.com) [great 😄]"
print(emoji_adjacent_to_link(line1))   # → True

# ✅ Detected – parenthesized description containing an emoji

line2 = "- [Demo](https://example.com) (🚀 launch)"
print(emoji_adjacent_to_link(line2))   # → True

# ❌ Not detected – description without emoji

line3 = "- [Demo](https://example.com) [quick start]"
print(emoji_adjacent_to_link(line3))   # → False

# ❌ Not detected – emoji inside the URL itself (should not count)

line4 = "- [Demo](https://example.com/🔧) [notes]"
print(emoji_adjacent_to_link(line4))   # → False

```

These scenarios mirror the unit tests in [`tests/test_emoji_detection.py`](https://github.com/emmabostian/developer-portfolios/blob/main/tests/test_emoji_detection.py), which validate both bracketed and parenthesized cases while ensuring emojis inside URLs are correctly ignored.

## Integration and Testing

The detection utilities power several maintenance workflows within the repository. The [`src/remove_emoji_in_readme.py`](https://github.com/emmabostian/developer-portfolios/blob/main/src/remove_emoji_in_readme.py) script demonstrates practical consumption of these functions, stripping emojis from link texts and adjacent descriptions during README processing.

Comprehensive test coverage exists in [`tests/test_emoji_detection.py`](https://github.com/emmabostian/developer-portfolios/blob/main/tests/test_emoji_detection.py), which exercises the detection logic across all supported markdown scenarios to prevent regression in emoji handling behavior.

## Summary

- **Two-function architecture**: `emoji_adjacent_to_link()` parses markdown syntax while `has_emoji()` performs Unicode code point analysis.
- **Dual pattern support**: The system detects emojis in both square-bracketed `[desc]` and parenthesized `(desc)` descriptions following markdown links.
- **Unicode range checking**: Emoji detection relies on predefined intervals (e.g., `0x1F300–0x1F5FF`) rather than external regex libraries.
- **URL exclusion**: Emojis appearing within the URL portion of markdown links are correctly ignored.
- **Source locations**: Core logic resides in [`src/alphabetical.py`](https://github.com/emmabostian/developer-portfolios/blob/main/src/alphabetical.py) lines 301-372, with tests in [`tests/test_emoji_detection.py`](https://github.com/emmabostian/developer-portfolios/blob/main/tests/test_emoji_detection.py).

## Frequently Asked Questions

### How does the system distinguish between emojis in URLs versus descriptions?

The regex patterns in `emoji_adjacent_to_link` specifically capture content after the URL-closing parenthesis `\)` and optional whitespace. The pattern `[^)]*` stops at the first closing parenthesis, ensuring the URL is excluded from capture groups. Only text within subsequent brackets or parentheses is examined, preventing emojis inside URLs from triggering false positives.

### What Unicode ranges does the emoji detector recognize?

The `_EMOJI_RANGES` tuple at [`alphabetical.py#L301-L319`](https://github.com/emmabostian/developer-portfolios/blob/master/src/alphabetical.py#L301-L319) includes standard emoji blocks such as `0x1F300–0x1F5FF` (Miscellaneous Symbols and Pictographs), `0x2600–0x26FF` (Miscellaneous Symbols), and other supplementary ranges. The `_is_emoji_codepoint` function checks if any character's integer value falls within these intervals.

### Can the detection handle both square brackets and parentheses for descriptions?

Yes. The implementation checks two distinct regex patterns sequentially. First, it attempts to match square-bracketed descriptions using `r"\]\s*\([^)]*\)\s*\[([^]]+)\]"`. If that fails, it falls back to parenthesized descriptions using `r"\]\s*\([^)]*\)\s*\(([^)]+)\)"`. Both patterns capture the description text and delegate to `has_emoji()` for validation.

### Where is this detection logic utilized in the repository?

Beyond the core implementation in [`src/alphabetical.py`](https://github.com/emmabostian/developer-portfolios/blob/main/src/alphabetical.py), the detection powers [`src/remove_emoji_in_readme.py`](https://github.com/emmabostian/developer-portfolios/blob/main/src/remove_emoji_in_readme.py), which automates the cleanup of emoji characters from portfolio listings. The test suite in [`tests/test_emoji_detection.py`](https://github.com/emmabostian/developer-portfolios/blob/main/tests/test_emoji_detection.py) provides continuous validation of these utilities to ensure reliable markdown processing across the project's maintenance workflows.