# gemtext ## Що це таке Gemtext — це формат документів протоколу Gemini: звичайний текст у UTF-8, де перші символи кожного рядка визначають, чим цей рядок є, тож клієнт може показати всю сторінку за один прохід згори донизу. Специфікація називає його гіпертекстовим форматом Gemini (the Gemini hypertext format), сервери позначають його типом носія `text/gemini`, а файли зазвичай мають розширення `.gmi`. Рядків буває шість видів. Рядок, що починається з `=>`, — це посилання: адреса, абсолютна чи відносна, і за нею необов'язковий підпис. Рядок із трьох зворотних лапок (backticks) вмикає або вимикає режим попередньо форматованого тексту, і все між двома такими рядками показується точно так, як написано, моноширинним шрифтом. Один, два чи три символи решітки дають заголовок, зірочка з пробілом дає пункт списку, а знак «більше» дає цитату. Усі інші рядки є звичайним текстом, і клієнт переносить його за шириною того екрана, на який він потрапить. ```text # Польові нотатки Текстовий рядок — це абзац, хоч який довгий. Клієнт його переносить. => /archive/ Старіші нотатки => gemini://example.org/ Капсула деінде * Пункт списку > Цитований рядок ``` Специфікація ділить ці шість на три основні типи, які мусить обробляти кожен клієнт (текст, посилання і перемикач попередньо форматованого тексту), і три, які мінімальний клієнт може показувати як звичайний текст. На цьому формат і закінчується. У ньому немає жирного шрифту й курсиву, таблиць, зображень усередині тексту, вкладеності та способу зробити клікабельним слово посеред речення. Парсер тримає в пам'яті один-єдиний біт стану: чи перебуває він усередині попередньо форматованого блоку. Gemtext найчастіше порівнюють із Markdown, на який він на перший погляд схожий. Різниця в тому, для чого кожен із них існує. Файл Markdown — це вихідний текст, написаний для того, щоб його перетворили на щось інше; файл gemtext — уже готовий документ, і показує його тільки клієнт читача. Свою єдину структурну звичку, посилання в окремому рядку, формат успадкував від старших меню Gopher. ## Чому це важливо Обрати gemtext означає обрати, хто керує сторінкою. Автор визначає структуру: які рядки є заголовками, які посиланнями і де стоїть код. Клієнт читача визначає решту, від шрифту й довжини рядка до кольорів, відступів і того, чи стануть заголовки змістом. Специфікація прямо каже, що формат не призначений давати авторові точний контроль над виглядом. Для одних видавців це полегшення, для інших кінець розмови, і краще знати, котрий випадок ваш, ще до конвертації першої сторінки. Полегшення полягає в тому, що зникає. Сторінка gemtext не має ні таблиці стилів, ні скрипту, ні вебшрифту, ні банера про cookies, ні пікселя стеження, і доглядати в ній треба лише слова. Сторінки маленькі, і їх швидко писати вручну. Посилання ніколи нічого не завантажують самі: специфікація забороняє клієнтові відкривати мережеве з'єднання тільки для того, щоб показати посилання, тож сторінка не може потай від читача підтягнути зображення чи шрифт від третьої сторони. Ціна так само відчутна. Gemtext доходить лише до людей, які користуються клієнтом Gemini, а це невелика аудиторія поруч із вебом. Форм у форматі немає; єдиний спосіб, у який капсула просить щось увести, — це код статусу в протоколі, а не щось у самому документі. До того ж текст має працювати без посилань усередині речень. Речення, написане для HTML, «деталі дивіться на сторінці з цінами», зберігає слова, але втрачає вказівник, тож добрий gemtext вимагає речень, які мають сенс і тоді, коли посилання стоїть рядком нижче. Тому для більшості організацій реалістичне питання звучить так: gemtext разом із вебсайтом, а не замість нього, з того самого джерела і в тому самому збиранні. За такої постановки gemtext коштує небагато, а заразом стає перевіркою тексту. Якщо сторінка й далі ясно читається як стовпчик текстових рядків і рядків-посилань, то її структура весь час була в самих словах. ## Як це виглядає на практиці Цей сайт публікується як gemtext поруч зі своїм HTML. Сторінка [Engineer у терміналі](/uk/cli/) наводить адресу капсули, `gemini://engineer.company/`, каже, що кожна сторінка сайту існує і в цьому форматі, і називає клієнти, які його читають: Amfora, Lagrange і Bombadillo в терміналі, Castor і Kristall у вікні. Вона ж пояснює причину. Одне розгортання записує одну теку, з якої читають усі входи, тож копія gemtext не може розійтися з HTML, а сторінка, що добре читається як gemtext, має справжню структуру, а не намальовану зверху. Як це збудовано, описано в [розповіді про віддзеркалення сайту в Gemini і Gopher](/uk/portfolio/mirrored-the-site-to-gemini-and-gopher-137/). Gemtext тут є форматом виводу того самого збирання, а не окремим конвеєром. Генераторові сайту додали власні типи носіїв і формати виводу, і кожна сторінка, розділ і термін таксономії дістали документ Gemini поруч зі своїм HTML і двійником у Markdown: усього 777, і віддає їх невеликий демон на тому самому хості. Нові формати позначено як неальтернативні подання, тож HTML не змінився ані на байт, і це виміряли, а не припустили. Альтернативні подання займають на диску приблизно дванадцять відсотків від власної ваги HTML. Шаблони, що стоять за цією копією, показують, що означає конвертація в gemtext. Кожне посилання виймають із речення: слова лишаються там, де вони потрібні реченню, а адреса переїжджає під текст окремим рядком `=>`. Позначки жирного шрифту зникають, пункти з дефісом стають зірочками, а блок коду між огорожами проходить без змін, бо огорожа Markdown і перемикач попередньо форматованого тексту в gemtext складаються з тих самих трьох зворотних лапок. ## Де виникають проблеми ### Обірвані рядки, які так і не зливаються Текст доходить до клієнта нерівним стовпчиком коротких рядків, обірваних посеред речення. Джерело було перенесене на 80 символах, як це часто буває з файлами Markdown, а специфікація забороняє клієнтові об'єднувати короткі текстові рядки, що йдуть підряд, у довші. Пишіть кожен абзац одним довгим рядком або доручіть конвертерові з'єднувати м'які розриви рядків, перш ніж він запише файл. ### Посилання, що виводять за межі капсули Перше ж посилання, за яким переходить читач, відкриває вебоглядач. Конвертер записав кожне посилання як абсолютну адресу `https://`, а клієнт Gemini передає такі адреси іншій програмі. Записуйте навігацію як шляхи від кореня, наприклад `/about/`, які ведуть усередину капсули, і залиште на кожній сторінці одне свідоме посилання на її вебверсію. ### Код, що злипається в один рядок Приклад коду з'являється одним довгим рядком, приліпленим до відкривної огорожі. Конвертер обробив блок як звичайний текст і злив його рядки з усім іншим. Розбивайте документ за огорожами раніше за будь-який інший крок, пропускайте кожен попередньо форматований блок так, як його написано, і дозволяйте рядкові-перемикачу нести щонайбільше короткий альтернативний текст, наприклад назву мови. ### Markdown, що перетворюється на буквальні символи Пункти з дефісом, подвійні зірочки, підкреслені заголовки, вкладені списки й посилання у квадратних дужках з'являються в клієнті точно так, як їх набрано. Gemtext розпізнає лише зірочку з пробілом як пункт списку і решітки як заголовок, а розмітки всередині рядка в ньому немає взагалі. Перетворюйте ці конструкції на виході або пишіть капсулу одразу в gemtext. ### Речення, що вказують у порожнечу Абзац каже «натисніть тут» або «як за посиланням вище», і читач лишається без напрямку. Посилання вийняли з речення, а слова, що лишилися, ніколи не казали, куди воно веде. Пишіть підписи посилань, які називають місце призначення, щоб і речення, і рядок `=>` мали сенс самі по собі. ## Що почитати далі - [A quick introduction to gemtext markup](https://geminiprotocol.net/docs/gemtext.gmi) — власний короткий огляд проєкту з усіма типами рядків і примітками для тих, хто знає Markdown. - [Gemini hypertext format specification](https://geminiprotocol.net/docs/gemtext-specification.gmi) — нормативний текст: типи рядків, стан парсера, правила перенесення, параметр `lang` і формальна граматика. - [Gemini network protocol specification](https://geminiprotocol.net/docs/protocol-specification.gmi) — як капсула віддає gemtext: запити, коди статусу й правила TLS, яких дотримується клієнт. - [Project Gemini FAQ](https://geminiprotocol.net/docs/faq.gmi) — міркування, що стоять за дизайном, зокрема чому посилання стоять в окремих рядках.