Підсвітка коду у технічних статтях на DOU

Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті.

Привіт, правильна підсвітка коду — це важливий атрибут кожної технічної статті, бо спрощує сприйняття. Тому розглянемо приклади налаштування підсвітки коду на DOU.
Стаття буде корисна авторам технічних статей.

Прості приклади

<div class="hl-wrap bash"><pre>cat hello.rs</pre></div>

cat hello.rs

<div class="hl-wrap rust"><pre>fn main() {
    println!("Hello World!");
}</pre></div>

fn main() {
    println!("Hello World!");
}

<div class="hl-wrap sql"><pre>CREATE TABLE user_online
(
    user_id BIGINT PRIMARY KEY,
    online  TIMESTAMP NOT NULL
);</pre></div>

CREATE TABLE user_online
(
    user_id BIGINT PRIMARY KEY,
    online  TIMESTAMP NOT NULL
);

<div class="hl-wrap json"><pre>{
  "scripts": {
    "build": "webpack --mode production"
  }
}</pre></div>

{
  "scripts": {
    "build": "webpack --mode production"
  }
}

Приклади зі спеціальними HTML-символами

Коли ваш код містить спеціальні HTML-символи, до прикладу «<» та «>» то код потрібно додатково трансформувати через HTML Escape.

Приклад правильного використання:

<div class="hl-wrap html"><pre>&lt;div id=&quot;input&quot;&gt;&lt;/div&gt;
&lt;div id=&quot;output&quot;&gt;&lt;/div&gt;</pre></div>

<div id="input"></div>
<div id="output"></div>

<div class="hl-wrap rust"><pre>struct State {
    rods: Vec&lt;Rod&gt;,
}</pre></div

struct State {
    rods: Vec<Rod>,
}

Якщо пропустите то в кращому випадку блок коду буде пустим:

<div class="hl-wrap html"><pre><div id="input"></div>
<div id="output"></div></pre></div>

<div id="input"></div>
<div id="output"></div>

Наведених прикладів достатньо для використання у більшості випадків.

Автоматичне визначення мови

На DOU для підсвітки коду використовується бібліотека highlight.js, це легко перевірити у веб-консолі (F12 або Ctrl+Shift+K):

console.log(hljs.versionString);

11.3.1

console.log(hljs.listLanguages()); // 36 languages

[
"bash", "c", "plaintext", "java",
"xml", "objectivec", "php", "php-template",
"sql", "erlang", "typescript", "swift",
"kotlin", "cpp", "csharp", "css",
"clojure", "protobuf", "diff", "r",
"rust", "ruby", "yaml", "elixir",
"shell", "markdown", "dart", "makefile",
"go", "scala", "json", "python",
"javascript", "ini", "lua", "graphql"
]

А якщо відкрити вихідний код будь-якої технічної статті (Ctrl+U), то побачите підключення бібліотеки highlight.js:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.3.1/styles/default.min.css">

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.3.1/highlight.min.js"></script>

<script>
    $(document).ready(function() {
        $(".hl-wrap").each(function(i, block) {
            $(block).find("pre").addClass(block.className.replace("hl-wrap", ""));
        });

        $("pre").each(function(i, block) {
            hljs.highlightBlock(block);
        });
    });
</script>

Як бачимо для підсвітки достатньо обернути код у тег pre:

<pre>console.log(hljs.versionString);</pre>

console.log(hljs.versionString);

<pre>fn main() {
    println!("Hello World!");
}</pre>

fn main() {
    println!("Hello World!");
}

<div class="hl-wrap rust"><pre>fn main() {
    println!("Hello World!");
}</pre></div>

fn main() {
    println!("Hello World!");
}

Автоматичне визначення мови через тег pre може помилятись.

Підсвітка коду для коментарів

Підсвітка коду доступна й для коментарів.

Якщо ви написали або відредагували коментар, то підсвітка включиться після перезавантаження сторінки.

Типові помилки

Перша помилка — це залишені зайві відступи з IDE:

	client := redis.NewClient(&redis.Options{
		Addr: "dragonflydb1:6379",
	})

	result, err := client.Ping(context.Background()).Result()
	require.NoError(t, err)
	require.Equal(t, "PONG", result)

Друга помилка — це коментарі, які ламають код, до прикладу у нас є Bash-команда з коментарем:

tree . (виводить дерево)

bash: syntax error near unexpected token `('

Має бути:

tree . # виводить дерево

Diff

Бібліотека highlight.js має підсвітку diff-у

<div class="hl-wrap diff"><pre>--- original-file.txt
+++ new-file.txt
@@ -1,4 +1,4 @@
 This is the original content.
-It will be removed in the new version.
+It has been updated in the new version.
 Other unchanged content.
</pre></div>

--- original-file.txt
+++ new-file.txt
@@ -1,4 +1,4 @@
 This is the original content.
-It will be removed in the new version.
+It has been updated in the new version.
 Other unchanged content.

Альтернативи

Перша альтернатива — це підключати приклади коду з codepen.io через iframe:

<iframe src="https://codepen.io/vityapoprozhuk/embed/BaqVwad?default-tab=html%2Cresult"></iframe>

Приклад зі статті «Методи підключення подій в VanillaJS».

Друга альтернатива — це підключати приклади коду з gist.github.com:

https://gist.github.com/YaroslavPodorvanov/79c4b1e9066238a6effeb09ecd732923