highlight.js/README.ru.md

   1 # Highlight.js
   2
   3 Highlight.js нужен для подсветки синтаксиса в примерах кода в блогах,
   4 форумах и вообще на любых веб-страницах. Пользоваться им очень просто,
   5 потому что работает он автоматически: сам находит блоки кода, сам
   6 определяет язык, сам подсвечивает.
   7
   8 Автоопределением языка можно управлять, когда оно не справляется само (см.
   9 дальше "Эвристика").
  10
  11
  12 ## Простое использование
  13
  14 Подключите библиотеку и стиль на страницу и повесть вызов подсветки на
  15 загрузку страницы:
  16
  17 ```html
  18 <link rel="stylesheet" href="styles/default.css">
  19 <script src="highlight.pack.js"></script>
  20 <script>hljs.initHighlightingOnLoad();</script>
  21 ```
  22
  23 Весь код на странице, обрамлённый в теги `<pre><code> .. </code></pre>`
  24 будет автоматически подсвечен. Если вы используете другие теги или хотите
  25 подсвечивать блоки кода динамически, читайте "Инициализацию вручную" ниже.
  26
  27 - Вы можете скачать собственную версию "highlight.pack.js" или сослаться
  28   на захостенный файл, как описано на странице загрузки:
  29   <http://softwaremaniacs.org/soft/highlight/download/>
  30
  31 - Стилевые темы можно найти в загруженном архиве или также использовать
  32   захостенные. Чтобы сделать собственный стиль для своего сайта, вам
  33   будет полезен справочник классов в файле [classref.txt][cr], который тоже
  34   есть в архиве.
  35
  36 [cr]: http://github.com/isagalaev/highlight.js/blob/master/classref.txt
  37
  38
  39 ## node.js
  40
  41 Highlight.js можно использовать в node.js. Библиотеку со всеми возможными языками можно
  42 установить с NPM:
  43
  44     npm install highlight.js
  45
  46 Также её можно собрать из исходников с только теми языками, которые нужны:
  47
  48     python tools/build.py -tnode lang1 lang2 ..
  49
  50 Использование библиотеки:
  51
  52 ```javascript
  53 var hljs = require('highlight.js');
  54
  55 // Если вы знаете язык
  56 hljs.highlight(lang, code).value;
  57
  58 // Автоопределение языка
  59 hljs.highlightAuto(code).value;
  60 ```
  61
  62
  63 ## Замена TABов
  64
  65 Также вы можете заменить символы TAB ('\x09'), используемые для отступов, на
  66 фиксированное количество пробелов или на отдельный `<span>`, чтобы задать ему
  67 какой-нибудь специальный стиль:
  68
  69 ```html
  70 <script type="text/javascript">
  71   hljs.tabReplace = '    '; // 4 spaces
  72   // ... or
  73   hljs.tabReplace = '<span class="indent">\t</span>';
  74
  75   hljs.initHighlightingOnLoad();
  76 </script>
  77 ```
  78
  79
  80 ## Инициализация вручную
  81
  82 Если вы используете другие теги для блоков кода, вы можете инициализировать их
  83 явно с помощью функции `highlightBlock(code, tabReplace, useBR)`. Она принимает
  84 DOM-элемент с текстом расцвечиваемого кода и опционально - строчку для замены
  85 символов TAB.
  86
  87 Например с использованием jQuery код инициализации может выглядеть так:
  88
  89 ```javascript
  90 $(document).ready(function() {
  91   $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
  92 });
  93 ```
  94
  95 `highlightBlock` можно также использовать, чтобы подсветить блоки кода,
  96 добавленные на страницу динамически. Только убедитесь, что вы не делаете этого
  97 повторно для уже раскрашенных блоков.
  98
  99 Если ваш блок кода использует `<br>` вместо переводов строки (т.е. если это не
 100 `<pre>`), передайте `true` третьим параметром в `highlightBlock`:
 101
 102 ```javascript
 103 $('div.code').each(function(i, e) {hljs.highlightBlock(e, null, true)});
 104 ```
 105
 106
 107 ## Эвристика
 108
 109 Определение языка, на котором написан фрагмент, делается с помощью
 110 довольно простой эвристики: программа пытается расцветить фрагмент всеми
 111 языками подряд, и для каждого языка считает количество подошедших
 112 синтаксически конструкций и ключевых слов. Для какого языка нашлось больше,
 113 тот и выбирается.
 114
 115 Это означает, что в коротких фрагментах высока вероятность ошибки, что
 116 периодически и случается. Чтобы указать язык фрагмента явно, надо написать
 117 его название в виде класса к элементу `<code>`:
 118
 119 ```html
 120 <pre><code class="html">...</code></pre>
 121 ```
 122
 123 Можно использовать рекомендованные в HTML5 названия классов:
 124 "language-html", "language-php". Также можно назначать классы на элемент
 125 `<pre>`.
 126
 127 Чтобы запретить расцветку фрагмента вообще, используется класс "no-highlight":
 128
 129 ```html
 130 <pre><code class="no-highlight">...</code></pre>
 131 ```
 132
 133
 134 ## Экспорт
 135
 136 В файле export.html находится небольшая программка, которая показывает и дает
 137 скопировать непосредственно HTML-код подсветки для любого заданного фрагмента кода.
 138 Это может понадобится например на сайте, на котором нельзя подключить сам скрипт
 139 highlight.js.
 140
 141
 142 ## Координаты
 143
 144 - Версия: 7.3
 145 - URL:    http://softwaremaniacs.org/soft/highlight/
 146 - Автор:  Иван Сагалаев (<maniac@softwaremaniacs.org>)
 147
 148 Лицензионное соглашение читайте в файле LICENSE.
 149 Список соавторов читайте в файле AUTHORS.ru.txt