Highlight Reference

Highlight Reference

Turn any ==highlight== into an instant knowledge lookup. هر ==هایلایت== را به یک مرجع دانش لحظه‌ای تبدیل کن.

---

What is Highlight Reference?

Highlight Reference turns Obsidian's built-in ==highlight== syntax into an interactive knowledge reference.

Hover over a highlighted word and instantly see its meaning — without opening another note or leaving your current workflow.

It works like a personal dictionary, glossary, or knowledge base that lives inside your notes.

The idea

==word== → hover → see the meaning
                     ↓
              edit or add it

Why Highlight Reference?

Instead of opening a separate glossary, using a custom syntax, or duplicating definitions across notes, Highlight Reference lets you keep your existing Markdown workflow.

• Uses Obsidian's native ==highlight== syntax
• Definitions are stored in regular Markdown notes
• References are connected through frontmatter
• Multiple reference notes are supported
• Definitions can contain Markdown
• Missing terms can be added directly from the tooltip

---

Who is it for?

Language learners Highlight vocabulary and instantly see translations or definitions.

Researchers Keep technical terms and concepts connected to your notes.

Students Build a personal study reference while taking notes.

Writers Create a personal terminology or style reference.

PKM users Connect notes to central reference files without duplicating information.

---

Features

---

Quick Start

1. Create a reference note

Create a normal Markdown note such as:

My Reference.md

Add one entry per line:

term :: meaning

For example:

==highlight== :: Text wrapped in == that becomes highlighted.

==frontmatter== :: Metadata stored at the top of an Obsidian note.

You can also write:

==term== Meaning of the term.

---

2. Connect the reference to your note

Add the reference to your note's frontmatter:

---
reference: "My Reference"
---

You can also use a wikilink:

---
reference: "[[My Reference]]"
---

---

3. Highlight a term

Write:

This is a ==highlight== example.

Now hover over highlight.

The definition appears instantly.

---

Example

Reference note

==photosynthesis== :: The process by which plants convert light energy into chemical energy.

==chloroplast== :: The organelle where photosynthesis takes place.

==glucose== :: A simple sugar produced during photosynthesis.

Study note

---
reference: "Biology Reference"
---

Plants use ==photosynthesis== to produce ==glucose==.
The process takes place inside the ==chloroplast==.

Hover over any highlighted term to see its definition.

---

Interactions

On mobile, editing and opening the reference can be done using the buttons inside the tooltip.

---

Command Palette

Open the Command Palette with Ctrl/Cmd + P.

Available commands include:

• Reload this note's reference
• Choose reference note for this note
• Add/Edit highlighted word at cursor

These commands are useful when you want to manage references without using the mouse.

---

Frontmatter References

The default frontmatter key is:

reference: "My Reference"

However, Highlight Reference also recognizes several common keys.

English keys

reference
dictionary
glossary
vocab
lexicon
source

Persian keys

مرجع
منبع
واژه‌نامه
لغتنامه
واژگان

The primary key can also be changed in plugin settings.

---

Multiple References

A note can use more than one reference.

For example:

---
reference: "Main Reference"
glossary: "Technical Terms"
---

Both reference files are loaded and merged.

If the same term exists in multiple references, the first matching entry takes priority.

This makes it possible to combine:

General Dictionary
        +
Technical Glossary
        +
Personal Vocabulary

without copying the definitions into your study note.

---

Reference Paths

All of these formats are supported:

Simple name

---
reference: "Glossary"
---

Wikilink

---
reference: "[[Main Glossary]]"
---

Full path

---
reference: "Folder/Subfolder/Glossary.md"
---

---

Multi-line Definitions

Definitions can span multiple lines.

Indent continuation lines with at least two spaces:

==photosynthesis== :: The process by which plants convert light energy
  into chemical energy.
  It takes place mainly inside chloroplasts.
  Oxygen is released as a byproduct.

You can also use blockquote continuation:

==photosynthesis== :: The process by which plants convert light energy.
> It takes place inside chloroplasts.
> Oxygen is released as a byproduct.

---

Markdown in Definitions

Definitions are not limited to plain text.

You can use Markdown such as:

==Obsidian== :: A knowledge management application with support for
**Markdown**, [[Wikilinks]], lists, and other Markdown features.

This allows reference entries to contain:

• Bold text
• Italic text
• Links
• Wikilinks
• Lists
• Other Markdown formatting

---

Spaced Repetition

Highlight Reference can work alongside the Spaced Repetition plugin.

Spaced Repetition on GitHub

This allows the same reference note to serve two purposes:

Reference Note
      │
      ├── Highlight Reference
      │      └── Hover definitions
      │
      └── Spaced Repetition
             └── Flashcards

Example

Your reference note:

==mitochondria== :: The organelle responsible for producing ATP. #flashcard

==ribosome== :: The cellular structure responsible for protein synthesis. #flashcard

==nucleus== :: The organelle that contains most of the cell's DNA. #flashcard

Your study note:

---
reference: "Biology Reference"
---

The ==mitochondria== produces energy, while ==ribosome==s
are responsible for protein synthesis.

Highlight Reference displays the definitions when you hover.

Spaced Repetition can use the same entries for review.

Why use both?

One source, multiple uses.

You write the definition once and reuse it for:

• Reading
• Note-taking
• Reference lookup
• Flashcards
• Spaced repetition

No need to maintain duplicate definitions.

Note: The exact flashcard hashtag depends on your Spaced Repetition settings.

For example:

#flashcard

or another tag configured in the plugin.

Check the Flashcard tags section in Spaced Repetition settings for the tag used by your vault.

---

Inline Meanings

Highlight Reference can optionally display definitions directly beside highlighted terms in Reading View.

For example:

The mitochondria [the organelle responsible for producing ATP]

This can be useful for:

• Study notes
• Revision notes
• Printed documents
• PDF exports
• Reading material

Enable Inline meaning in the plugin settings.

---

Term Normalization

Highlight Reference normalizes terms before comparing them.

This is especially useful for Persian and Arabic text.

For example:

كتاب
کتاب

are treated as the same term after normalization.

---

Smart Caching

Reference files are cached to avoid unnecessary repeated parsing.

The cache is associated with the file's modification state.

When a reference file changes:

1. The plugin detects the change.
2. The old cache is invalidated.
3. The reference is loaded again.

You can also manually reload a reference from the Command Palette:

Reload this note's reference

---

Settings

Hover Delay

The hover delay can be adjusted between:

0–1000 ms

A shorter delay makes lookup feel more immediate.

A longer delay can reduce accidental tooltips while moving the mouse across the page.

---

Mobile Support

Highlight Reference supports mobile Obsidian.

The plugin uses the browser's visualViewport API when displaying input interfaces on mobile.

This helps prevent dialogs from being hidden behind the on-screen keyboard.

Version 1.0.2 includes a fix for mobile dialogs appearing underneath the keyboard.

---

Troubleshooting

Check the following:

1. Make sure your note contains a valid reference in frontmatter.
2. Make sure the reference note exists.
3. Check that the path or note name is correct.
4. Run Reload this note's reference from the Command Palette.
5. Check the status bar for the number of loaded entries.

1. Make sure Show meaning on hover is enabled.
2. Try lowering the Hover delay.
3. Test the highlight in Reading View.
4. Make sure the highlighted term exists in the connected reference.

Save the reference note first.

The plugin automatically detects changes and refreshes its cache.

If the change still does not appear, use:

Command Palette → Reload this note's reference

Highlight Reference normalizes terms before comparison.

For example:

كتاب
کتاب

are considered equivalent.

If exact matching is important, use more specific reference entries.

Make sure you are using Highlight Reference 1.0.2 or later.

The mobile viewport handling was improved in version 1.0.2.

---

Technical Details

Built with the Obsidian API

Highlight Reference uses:

Plugin
Modal
FuzzySuggestModal
MarkdownRenderer
metadataCache
registerMarkdownPostProcessor

Storage

Reference paths are read from note frontmatter through Obsidian's metadata cache.

Rendering

Inline meanings are rendered using:

registerMarkdownPostProcessor

Mobile

Mobile positioning uses:

visualViewport

Dependencies

Highlight Reference has:

No external dependencies

---

File Structure

.obsidian/plugins/highlight-reference/
├── main.js
├── manifest.json
└── styles.css

---

Installation

Community Plugins

1. Open Obsidian.
2. Go to Settings → Community plugins.
3. Click Browse.
4. Search for Highlight Reference.
5. Click Install.
6. Click Enable.

Manual Installation

Download the latest release:

Highlight Reference Releases

Copy these files:

main.js
manifest.json
styles.css

into:

.obsidian/plugins/highlight-reference/

Then restart Obsidian and enable the plugin.

BRAT

For development or beta versions:

1. Install BRAT.
2. Open BRAT settings.
3. Select Add Beta plugin.
4. Enter:

https://github.com/singhaf9270/obsidian-highlight-reference

5. Click Add Plugin.

---

Contributing

Bug reports, ideas, suggestions, and pull requests are welcome.

Report an issue

View the source code on GitHub

If you find Highlight Reference useful, consider giving the repository a ⭐.

---

License

Released under the MIT License.

See the LICENSE file for details.

---

Follow

Obsidian tutorials and Persian content:

• Telegram — @obsidiantut
• Bale — @obsidiantut
• YouTube — @obsidiantut

---

هایلایت رفرنس چیست؟

Highlight Reference سینتکس معمولی ==هایلایت== در Obsidian را به یک مرجع دانش تعاملی تبدیل می‌کند.

کافی است موس را روی یک کلمهٔ هایلایت‌شده ببری تا معنی یا توضیح آن بدون باز کردن فایل دیگری نمایش داده شود.

در واقع می‌توانی آن را مثل یک:

واژه‌نامه، فرهنگ اصطلاحات یا پایگاه دانش شخصی داخل یادداشت‌ها

در نظر بگیری.

ایدهٔ اصلی

==کلمه== → هاور → نمایش معنی
                    ↓
              ویرایش یا افزودن

---

چرا Highlight Reference؟

لازم نیست:

• پنل جداگانه‌ای باز کنی.
• سینتکس جدیدی یاد بگیری.
• تعریف یک کلمه را در چند یادداشت تکرار کنی.

پلاگین با همان قابلیت داخلی هایلایت Obsidian کار می‌کند:

==کلمه==

و تعریف‌ها را در فایل‌های Markdown معمولی نگه می‌دارد.

---

مناسب چه کسانی است؟

زبان‌آموزها برای دیدن سریع معنی و ترجمهٔ واژه‌های جدید.

دانشجوها برای ساخت یک مرجع شخصی در کنار یادداشت‌های درسی.

پژوهشگران برای ثبت اصطلاحات تخصصی و علمی.

نویسنده‌ها برای ساخت واژه‌نامه یا راهنمای اصطلاحات شخصی.

کاربران PKM برای اتصال یادداشت‌ها به مراجع مرکزی بدون ایجاد اطلاعات تکراری.

---

قابلیت‌ها

---

شروع سریع

۱. ساخت مرجع

یک یادداشت معمولی بساز:

واژه‌نامه.md

و داخل آن بنویس:

عنوان :: توضیح

مثلاً:

==فتوسنتز== :: فرایندی که گیاهان با استفاده از نور، انرژی شیمیایی تولید می‌کنند.

==کلروپلاست== :: اندامکی که فرایند فتوسنتز در آن انجام می‌شود.

---

۲. اتصال مرجع

در ابتدای یادداشتت بنویس:

---
reference: "واژه‌نامه"
---

یا:

---
reference: "[[واژه‌نامه]]"
---

---

۳. استفاده از هایلایت

در متن بنویس:

گیاهان از طریق ==فتوسنتز== انرژی تولید می‌کنند.

حالا موس را روی فتوسنتز ببر.

تعریف آن نمایش داده می‌شود.

---

مثال کامل

یادداشت مرجع

==میتوکندری== :: اندامکی که نقش مهمی در تولید ATP و تأمین انرژی سلول دارد.

==ریبوزوم== :: ساختاری که در فرایند ساخت پروتئین نقش دارد.

==هسته== :: بخشی از سلول که بیشتر DNA سلول در آن قرار دارد.

یادداشت مطالعه

---
reference: "مرجع زیست"
---

سلول دارای بخش‌های مختلفی است.
==میتوکندری== در تأمین انرژی نقش دارد و ==ریبوزوم==
در ساخت پروتئین فعالیت می‌کند.

با قرار دادن موس روی هر کلمه، توضیح آن نمایش داده می‌شود.

---

تعامل با هایلایت‌ها

در موبایل، دکمه‌های داخل تولتیپ برای ویرایش و باز کردن مرجع در دسترس هستند.

---

دستورات پالت

با Ctrl/Cmd + P می‌توانی به این دستورات دسترسی داشته باشی:

• بارگذاری دوبارهٔ مرجع این یادداشت
• انتخاب یادداشت مرجع برای این یادداشت
• افزودن/ویرایش عنوان هایلایت زیر نشانگر

---

چند مرجع هم‌زمان

می‌توانی یک یادداشت را به چند مرجع متصل کنی:

---
reference: "مرجع اصلی"
glossary: "اصطلاحات تخصصی"
---

پلاگین هر دو فایل را می‌خواند و ورودی‌ها را با هم ترکیب می‌کند.

اگر یک عنوان در چند مرجع وجود داشته باشد، اولین ورودی پیدا‌شده اولویت دارد.

مثلاً می‌توانی داشته باشی:

واژه‌نامه عمومی
        +
اصطلاحات تخصصی
        +
واژه‌های شخصی

بدون اینکه تعریف‌ها را در یادداشت‌های مختلف کپی کنی.

---

کلیدهای Frontmatter

کلید پیش‌فرض:

reference: "واژه‌نامه"

اما پلاگین کلیدهای دیگری را نیز می‌شناسد.

انگلیسی

reference
dictionary
glossary
vocab
lexicon
source

فارسی

مرجع
منبع
واژه‌نامه
لغتنامه
واژگان

کلید اصلی نیز از بخش تنظیمات قابل تغییر است.

---

مسیر مرجع

نام ساده

---
reference: "واژه‌نامه"
---

ویکی‌لینک

---
reference: "[[واژه‌نامه اصلی]]"
---

مسیر کامل

---
reference: "پوشه/زیرپوشه/واژه‌نامه.md"
---

---

توضیحات چندخطی

تعریف‌ها می‌توانند چندخطی باشند.

برای ادامهٔ توضیح، خط‌های بعدی را با حداقل دو فاصله شروع کن:

==فتوسنتز== :: فرایندی که گیاهان با استفاده از نور
  انرژی شیمیایی تولید می‌کنند.
  این فرایند عمدتاً در کلروپلاست انجام می‌شود.

یا:

==فتوسنتز== :: فرایندی که گیاهان با استفاده از نور انرژی تولید می‌کنند.
> این فرایند در کلروپلاست انجام می‌شود.
> اکسیژن نیز به‌عنوان محصول جانبی آزاد می‌شود.

---

پشتیبانی از Markdown

تعریف‌ها می‌توانند Markdown داشته باشند:

==Obsidian== :: یک برنامهٔ مدیریت دانش با پشتیبانی از
**Markdown**، [[Wikilink]] و فهرست‌ها.

بنابراین می‌توانی داخل تعریف‌ها از موارد زیر استفاده کنی:

• متن ضخیم
• متن ایتالیک
• لینک
• ویکی‌لینک
• فهرست
• قالب‌بندی Markdown

---

Spaced Repetition

Highlight Reference می‌تواند در کنار پلاگین Spaced Repetition استفاده شود.

Spaced Repetition در GitHub

ایده ساده است:

              یادداشت مرجع
                   │
          ┌────────┴────────┐
          ↓                 ↓
 Highlight Reference   Spaced Repetition
          ↓                 ↓
      نمایش معنی          فلش‌کارت

مثلاً:

==میتوکندری== :: اندامکی که در تولید ATP نقش دارد. #flashcard

==ریبوزوم== :: ساختار مسئول ساخت پروتئین است. #flashcard

==هسته== :: محل قرارگیری بیشتر DNA سلول است. #flashcard

در یادداشت مطالعه:

---
reference: "مرجع زیست"
---

==میتوکندری== در تأمین انرژی سلول نقش دارد.

حالا:

• Highlight Reference هنگام هاور، تعریف را نشان می‌دهد.
• Spaced Repetition می‌تواند همان ورودی‌ها را برای مرور استفاده کند.

مزیت اصلی

یک بار بنویس، چند بار استفاده کن.

همان تعریف می‌تواند برای:

• مطالعه
• یادداشت‌برداری
• مرجع سریع
• فلش‌کارت
• مرور فاصله‌دار

استفاده شود.

نوع هشتگ فلش‌کارت به تنظیمات Spaced Repetition بستگی دارد. بخش Flashcard tags را در تنظیمات آن بررسی کن.

---

معنی درون‌خطی

با فعال کردن گزینهٔ درج توضیح کنار هایلایت، معنی در Reading View کنار کلمه نمایش داده می‌شود.

این قابلیت برای موارد زیر مفید است:

• یادداشت‌های آموزشی
• مرور درسی
• چاپ
• خروجی PDF
• متون آموزشی

---

نرمال‌سازی واژه‌ها

برای اینکه تطبیق فارسی و عربی بهتر انجام شود، واژه‌ها قبل از مقایسه نرمال می‌شوند.

بنابراین:

كتاب
کتاب

به‌عنوان یک عنوان در نظر گرفته می‌شوند.

---

کش هوشمند

فایل‌های مرجع برای جلوگیری از پردازش اضافی کش می‌شوند.

وقتی فایل مرجع تغییر کند:

1. تغییر شناسایی می‌شود.
2. کش قبلی کنار گذاشته می‌شود.
3. فایل دوباره خوانده می‌شود.

همچنین می‌توانی از Command Palette به‌صورت دستی مرجع را Reload کنی.

---

تنظیمات

تاخیر هاور بین:

0 تا 1000 میلی‌ثانیه

قابل تنظیم است.

---

پشتیبانی از موبایل

Highlight Reference برای Obsidian موبایل نیز طراحی شده است.

برای مدیریت بهتر موقعیت پنجره‌ها هنگام باز شدن کیبورد از:

visualViewport

استفاده می‌شود.

مشکل قرار گرفتن پنجره زیر کیبورد در نسخهٔ 1.0.2 برطرف شده است.

---

عیب‌یابی

1. وجود reference یا یکی از کلیدهای مجاز را در Frontmatter بررسی کن.
2. مطمئن شو فایل مرجع وجود دارد.
3. مسیر مرجع را بررسی کن.
4. دستور بارگذاری دوبارهٔ مرجع این یادداشت را اجرا کن.
5. تعداد ورودی‌های بارگذاری‌شده را در Status Bar بررسی کن.

1. گزینهٔ نمایش معنی با هاور را بررسی کن.
2. مقدار تاخیر هاور را کاهش بده.
3. در Reading View امتحان کن.
4. مطمئن شو عنوان موردنظر در مرجع وجود دارد.

ابتدا فایل مرجع را ذخیره کن.

پلاگین تغییرات را به‌صورت خودکار تشخیص می‌دهد.

اگر تغییر نمایش داده نشد:

Command Palette
→ Reload this note's reference

را اجرا کن.

پلاگین واژه‌ها را قبل از مقایسه نرمال می‌کند.

برای مثال:

كتاب
کتاب

معادل در نظر گرفته می‌شوند.

اگر تطبیق دقیق‌تری لازم داری، از عنوان‌های مشخص‌تر استفاده کن.

از نسخهٔ 1.0.2 یا جدیدتر استفاده کن.

مدیریت موقعیت پنجره‌ها در این نسخه بهبود یافته است.

---

جزئیات فنی

Highlight Reference از APIهای زیر Obsidian استفاده می‌کند:

Plugin
Modal
FuzzySuggestModal
MarkdownRenderer
metadataCache
registerMarkdownPostProcessor

ذخیره‌سازی

مسیر مراجع از Frontmatter یادداشت و از طریق metadataCache خوانده می‌شود.

رندر

معنی‌های درون‌خطی با:

registerMarkdownPostProcessor

پردازش می‌شوند.

موبایل

برای مدیریت موقعیت رابط کاربری:

visualViewport

استفاده می‌شود.

وابستگی خارجی

این پلاگین:

هیچ وابستگی خارجی ندارد.

---

ساختار فایل‌ها

.obsidian/plugins/highlight-reference/
├── main.js
├── manifest.json
└── styles.css

---

نصب

نصب از Community Plugins

1. Obsidian را باز کن.
2. به Settings → Community plugins برو.
3. روی Browse کلیک کن.
4. عبارت Highlight Reference را جستجو کن.
5. روی Install کلیک کن.
6. پلاگین را Enable کن.

نصب دستی

آخرین نسخه Highlight Reference

این سه فایل را دانلود کن:

main.js
manifest.json
styles.css

و داخل این مسیر قرار بده:

.obsidian/plugins/highlight-reference/

سپس Obsidian را دوباره اجرا و پلاگین را فعال کن.

نصب با BRAT

برای نسخه‌های آزمایشی:

1. BRAT را نصب کن.
2. وارد تنظیمات BRAT شو.
3. Add Beta plugin را انتخاب کن.
4. این آدرس را وارد کن:

https://github.com/singhaf9270/obsidian-highlight-reference

5. روی Add Plugin کلیک کن.

---

مشارکت

اگر ایده، پیشنهاد یا باگی داری، خوشحال می‌شوم آن را در GitHub مطرح کنی.

گزارش Issue

مشاهده کد منبع در GitHub

اگر پلاگین برایت مفید بود، می‌توانی به مخزن ⭐ بدهی.

---

مجوز

این پروژه تحت مجوز MIT License منتشر شده است.

برای جزئیات، فایل LICENSE را ببین.

---

آموزش‌های Obsidian

برای آموزش‌ها و مطالب فارسی Obsidian:

• تلگرام — @obsidiantut
• بله — @obsidiantut
• یوتیوب — @obsidiantut

---

ساخته شده با ❤️ برای جامعهٔ Obsidian