@nerox_dev/remark-entity-chips

Transform entity mentions into rich, visual chips in Markdown. Works with Astro, Next.js, Docusaurus, and any remark-based pipeline.

Live Demo (Astro) | Live Demo (Next.js)

Examples

Entity Mentions (@[entity])

Entities in the built-in database are automatically resolved with their name, favicon, and URL.

Entity Mentions with Custom URL (@[entity](url))

Use the entity's favicon and display name but link to a custom URL.

Custom Chips with Domain Favicon (@[text](url))

If the text doesn't match an entity but the URL domain is in the database, the domain's favicon is used.

Auto-Detected Bare URLs (enabled by default)

Bare platform URLs in text are automatically transformed into chips.

Markdown Links (opt-in)

Standard markdown links [text](url) can optionally be transformed into chips. Disabled by default to avoid breaking existing content.

Installation

npm install @nerox_dev/remark-entity-chips

Quick Start

Astro

// astro.config.mjs
import { defineConfig } from "astro/config";
import entityChips from "@nerox_dev/remark-entity-chips";

export default defineConfig({
  markdown: {
    remarkPlugins: [entityChips],
  },
});

Configuration

import entityChips from "@nerox_dev/remark-entity-chips";

[
  entityChips,
  {
    // Transform bare URLs into chips (default: true)
    autoDetectUrls: true,

    // Transform markdown links [text](url) into chips (default: false)
    transformMarkdownLinks: false,

    // Custom CSS class names
    classNames: {
      chip: "entity-chip", // default
      favicon: "entity-favicon", // default
      name: "entity-name", // default
    },

    // Custom icon resolver (optional)
    iconResolver: (slug, entity) => {
      return `https://cdn.example.com/icons/${slug}.png`;
      // return null to fallback to entity.icon or Google Favicon
    },
  },
];

| Option | Type | Default | Description | | ------------------------ | -------------- | ------------------ | -------------------------------------------------- | | autoDetectUrls | boolean | true | Transform bare platform URLs into chips | | transformMarkdownLinks | boolean | false | Transform [text](url) links into chips | | classNames.chip | string | "entity-chip" | CSS class for the chip wrapper | | classNames.favicon | string | "entity-favicon" | CSS class for the favicon image | | classNames.name | string | "entity-name" | CSS class for the label text | | iconResolver | IconResolver | undefined | Custom function to resolve icon URLs (see below) |

Custom Entities

You can extend or override the built-in entity database by creating an entity-chips.json file in your project root.

{
  "my-company": {
    "name": "My Company",
    "domain": "mycompany.com",
    "url": "https://mycompany.com",
    "category": "saas",
    "type": "company"
  }
}

The plugin automatically detects this file and merges it with the built-in database. Custom entries override built-in ones with the same key.

Then use it in Markdown:

Check out @[my-company] for more info.

Custom Icons

Each entity supports an optional icon field for custom favicon sources — a local path served by your framework (e.g. from public/) or an absolute URL to a CDN:

{
  "my-company": {
    "name": "My Company",
    "domain": "mycompany.com",
    "url": "https://mycompany.com",
    "category": "saas",
    "type": "company",
    "icon": "/entities/my-company.webp"
  },
  "partner": {
    "name": "Partner Inc",
    "domain": "partner.io",
    "url": "https://partner.io",
    "category": "saas",
    "type": "company",
    "icon": "https://cdn.example.com/icons/partner.png"
  }
}

Icon Resolution Priority

The plugin resolves icons in this order:

1. iconResolver option — if provided and returns a string, that URL is used
2. entity.icon field — if set on the entity (from entity-chips.json or built-in)
3. Google Favicon API — default fallback using the entity's domain

// Example: serve all icons from a CDN, fallback to default
[
  entityChips,
  {
    iconResolver: (slug, entity) => {
      if (entity?.icon) return entity.icon;
      return `https://cdn.example.com/favicons/${slug}.webp`;
    },
  },
];

Supported Entities

The built-in database includes 200+ entities across categories:

| Category | Examples | | -------------- | --------------------------------------------------------- | | Frameworks | React, Vue, Angular, Svelte, Astro, Next.js, Tailwind CSS | | Dev Tools | GitHub, GitLab, VS Code, Docker, Vite, ESLint | | AI | OpenAI, Anthropic, Claude, Hugging Face | | Fintech | Stripe, PayPal, Wise, Square | | Social | YouTube, X, LinkedIn, Discord, Reddit | | Cloud | AWS, Google Cloud, Azure, Vercel, Netlify, Cloudflare | | Databases | PostgreSQL, MongoDB, Redis, Supabase, Firebase, Prisma | | SaaS | Notion, Slack, Figma, Linear, Jira |

Styling

Add CSS to style the chips:

.entity-chip {
  display: inline-flex;
  align-items: center;
  gap: 4px;
  padding: 2px 8px;
  border-radius: 16px;
  background: #f0f0f0;
  text-decoration: none;
  color: #333;
  font-size: 0.9em;
  border: 1px solid #ddd;
}

.entity-chip:hover {
  background: #e0e0e0;
}

.entity-favicon {
  border-radius: 2px;
}

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by any of the companies or projects whose names or trademarks appear in the built-in entity database. All trademarks, logos, and brand names are the property of their respective owners and are used here solely for identification purposes.

Favicons are fetched at runtime via Google's public favicon service and are not bundled or redistributed with this package.

License

MIT