آموزش جامع Highlight.js

📚معرفی و شروع سریع

Highlight.js کدهای داخل صفحه را به‌صورت خودکار شناسایی و رنگ‌آمیزی می‌کند. کافیست کد را داخل <pre><code> بگذارید، یک تم CSS و فایل JS را اضافه کنید و hljs.highlightAll() را صدا بزنید.

<!-- HTML — در head: یک تم -->
<link rel="stylesheet" href="styles/github-dark.min.css">

<!-- کد شما -->
<pre><code class="language-js">
const x = 10;
console.log(x);
</code></pre>

<!-- در انتهای body -->
<script src="highlight.min.js"></script>
<script>hljs.highlightAll();</script>

// اولین مثال Highlight.js
const message = "سلام دنیا!";
function greet(name) {
  return `${message} ${name}`;
}
console.log(greet("HubGit"));

⚡highlightAll و خودکار

hljs.highlightAll() همهٔ بلوک‌های <pre><code> صفحه را یک‌جا رنگ‌آمیزی می‌کند. معمولاً بعد از بارگذاری DOM صدا زده می‌شود.

// رنگ‌آمیزی همهٔ بلوک‌های کد در صفحه
document.addEventListener('DOMContentLoaded', () => {
  hljs.highlightAll();
});

// محتوای جدید (Ajax/SPA)؟ دوباره صدا بزنید
function loadContent(html) {
  container.innerHTML = html;
  hljs.highlightAll();   // بلوک‌های جدید هم رنگ می‌شوند
}

# Python
def factorial(n):
    return 1 if n == 0 else n * factorial(n - 1)
print(factorial(5))

/* CSS */
.btn {
  background: #88ce02;
  border-radius: 8px;
  transition: all .2s;
}

🎨تم‌ها (Themes)

ظاهر رنگ‌آمیزی فقط با تعویض فایل CSS تم تغییر می‌کند — کد JS دست نمی‌خورد. Highlight.js بیش از ۲۵۰ تم رسمی دارد (github، monokai، atom-one-dark و ...).

// فقط لینک CSS را عوض کنید:
<link href="styles/github-dark.min.css">   // تیره
<link href="styles/github.min.css">        // روشن

// با دکمه‌های بالا تم را عوض کنید
async function fetchUser(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error('خطا!');
  return res.json();
}

🌐زبان مشخص

برای دقت بیشتر، زبان را صریح با کلاس language-xxx تعیین کنید. این از حدس اشتباه جلوگیری می‌کند و سریع‌تر هم هست.

<!-- زبان صریح -->
<pre><code class="language-json">...</code></pre>
<pre><code class="language-bash">...</code></pre>

// جلوگیری از رنگ‌آمیزی یک بلوک:
<code class="nohighlight">...</code>

{
  "name": "hubgit",
  "version": "1.0.0",
  "offline": true,
  "libraries": 30
}

# نصب و اجرا
npm install highlight.js
node server.js --port 3000

🔎highlightElement

برای رنگ‌آمیزی فقط یک عنصر مشخص (مثلاً بلوکی که تازه به DOM اضافه کرده‌اید) از hljs.highlightElement() استفاده کنید.

const el = document.querySelector('#myCode');
hljs.highlightElement(el);

// مثال: تولید بلوک کد به‌صورت داینامیک
const pre = document.createElement('pre');
pre.innerHTML = '<code class="language-js">let a = 1;</code>';
box.appendChild(pre);
hljs.highlightElement(pre.querySelector('code'));

📝highlight() رشته‌ای

اگر کد را به‌صورت رشته دارید و خروجی HTML رنگ‌آمیزی‌شده می‌خواهید (بدون درج مستقیم در DOM)، از hljs.highlight() استفاده کنید.

const code = 'const x = [1, 2, 3].map(n => n * 2);';

const result = hljs.highlight(code, { language: 'javascript' });

result.value;     // رشتهٔ HTML رنگ‌آمیزی‌شده
result.language;  // 'javascript'
result.relevance; // امتیاز اطمینان

// درج در صفحه:
output.innerHTML = result.value;

🤖تشخیص خودکار زبان

وقتی زبان را نمی‌دانید، hljs.highlightAuto() آن را حدس می‌زند و امتیاز اطمینان (relevance) برمی‌گرداند.

const result = hljs.highlightAuto('SELECT * FROM users WHERE id = 1;');

result.language;        // 'sql'
result.relevance;       // امتیاز زبان برتر
result.secondBest;      // حدس دوم

// محدود کردن زبان‌های حدس برای دقت بیشتر
hljs.highlightAuto(code, ['js', 'python', 'sql']);

🔢شماره خط و کپی کد

Highlight.js به‌صورت پیش‌فرض شماره خط ندارد، اما با کمی کد می‌توان آن را افزود. دکمهٔ «کپی» هم بسیار رایج است.

// دکمهٔ کپی ساده
function copyCode(btn) {
  const code = btn.parentElement.querySelector('code').innerText;
  navigator.clipboard.writeText(code);
  btn.textContent = '✓ کپی شد';
}

const greet = (name) => {
  const hour = new Date().getHours();
  const time = hour < 12 ? 'صبح' : 'عصر';
  return `${time} بخیر، ${name}!`;
};

⚙تنظیمات و configure

با hljs.configure() رفتار کلی را قبل از رنگ‌آمیزی تنظیم کنید.

hljs.configure({
  cssSelector:   'pre code',    // کدام عناصر هدف باشند
  languages:     ['js', 'python', 'css'],  // محدود کردن تشخیص خودکار
  ignoreUnescapedHTML: false,  // هشدار HTML خام
  throwUnescapedHTML:  false
});

// ثبت زبان دلخواه (اگر فقط هسته را بارگذاری کرده‌اید)
hljs.registerLanguage('js', javascriptLang);

// نام مستعار برای زبان
hljs.registerAliases(['node'], { languageName: 'javascript' });

🔥الگوهای رایج

وبلاگ / مستندات

متداول‌ترین کاربرد: رنگ‌آمیزی نمونه‌کدها در مقالات فنی. فقط highlightAll() بعد از رندر محتوا کافی است.

بلوک کد قابل کپی (کامل)

<!-- ساختار آمادهٔ کپی -->
<div class="code-card">
  <button class="copy-btn" onclick="copyCode(this)">کپی</button>
  <pre><code class="language-js">...</code></pre>
</div>

راهنمای API زنده

// GET /api/posts
fetch('/api/posts', {
  headers: { 'Authorization': 'Bearer ' + token }
})
  .then(r => r.json())
  .then(posts => posts.forEach(renderPost))
  .catch(err => console.error('خطا:', err));

📄 جمع‌بندی سریع

🚀زمین بازی کد (Playground)

کد را در تب HTML داخل <pre><code> بگذار و با Highlight.js رنگ‌آمیزی‌اش کن. زبان و تم را تغییر بده و ▶ اجرا را بزن. نسخهٔ ۱۱.۹.۰ با تم github-dark آفلاین بارگذاری می‌شود.