Публікація чистого тексту з допомогою Pandoc і Markdown
Автори: Денніс Тенен і Грант Вітхофф Переклад: Дмитро Марченко Оригінал уроку: https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown
У цьому уроці ви дізнаєтеся про основи Markdown - зручного для читання і запису синтаксису розмітки звичайного тексту, а також Pandoc - інструмент командного рядка, який перетворює звичайний текст у красиво форматовані файли: PDF, .docx, HTML, LaTeX, слайди тощо.
Цілі
У цьому уроці ви спочатку ознайомитеся з основами Markdown — полегшеною мовою розмітки даних, зручної для читання та написання звичайного тексту, створення синтаксису розмітки, тощо — а також Pandoc — інструмента командного рядка, який перетворює звичайний текст у різні типи відформатованих файлів, таких як: PDF, docx, HTML, LaTeX, слайди презентацій. Завдяки Pandoc як інструменту цифрового набору тексту ви можете використовувати синтаксис Markdown, щоб додавати малюнки, бібліографію, форматувати та легко змінювати стилі цитування від Chicago до MLA, усі з використанням звичайного тексту.
Урок не вимагає попередніх технічних знань, але він поступово ускладнюється, оскільки ми часто пропонуємо більш просунуті техніки наприкінці кожного розділу. Вони чітко позначені, і їх можна переглянути після набуття практики та експериментів.
Замість того, щоб механічно дотримуватись вказівок, ми рекомендуємо вам спробувати зрозуміти запропоновані тут рішення як методологію, яку, можливо, потрібно буде додатково адаптувати відповідно до вашого середовища та робочого процесу. Налаштування необхідних інструментів є чи не найбільшою перешкодою для участі. Виділіть собі достатньо часу та терпіння, щоб правильно встановити все, або зробіть це разом із колегою, який має подібні налаштування, і допомагайте один одному. Також ви можете використати розділ "Корисні ресурси" нижче, якщо ви відчуваєте що вам потрібно більше інформації.
Філософія
Написання, зберігання та пошук документів є ключовими елементами в робочому процесі гуманітарних досліджень. І все ж багато авторів будують свою практику на пропрієтарних інструментах і форматах (програмні продукти, права на які належать певній компанії чи розробнику, і використання яких обмежується умовами ліцензії; інша назва - власницькі інструменти), які іноді не відповідають навіть основним вимогам наукового письма. Можливо, ви відчуваєте розчарування через крихкість виносок, бібліографії, малюнків і чернеток книг, створених у Microsoft Word або Google Docs. Тим не менш, більшість журналів все ще наполягають на поданні матеріалів у форматі docx.
Ця залежність від закритих інструментів і форматів не тільки викликає особисте розчарування, але й має довгострокові негативні наслідки для академічної спільноти. У такому середовищі журнали повинні доручати набір текстів аутсорсинговим компаніям, що відчужує авторів від матеріального контексту публікації та додає додаткові непотрібні бар’єри для вільної циркуляції знань.
Коли ви використовуєте MS Word, Google Docs або OpenOffice для написання документів, ви бачите не те, що ви отримуєте. Під видимим шаром слів, речень і абзаців лежить складний механізм, зрозумілий лише машинам. Через цей прихований механізм, правильне відтворення ваших файлів docx і PDF залежать від пропрієтарних інструментів. Такі документи важко шукати, друкувати та конвертувати в інші формати файлів.
Крім того, час, витрачений на форматування вашого документа в MS Word або OpenOffice, марнується, оскільки все це форматування видаляє видавець під час верстки публікацій. Як автори, так і видавці виграють від обміну файлами з мінімальним форматуванням, залишаючи верстку на завершальний етап підготовки видання.
Ось тут технологія Markdown стане у нагоді. — це синтаксис для явного позначення семантичних елементів у документі, а не в прихованому шарі. Ідея полягає в тому, щоб визначити одиниці та тип форматування тексту, які є вимогою видавництва, наприклад заголовки, розділи, підрозділи, виноски та ілюстрації. Принаймні, ваші файли завжди залишаться зрозумілими для вас, навіть якщо текстовий редактор, яким ви зараз користуєтеся, перестане працювати або його перестане підтримувати розробник.
Таким чином, автор унезалежнюється в процесі писання від інструменту. Markdown можна використовувати в будь-якому текстовому редакторі, також він пропонує розвинену екосистему технічних можливостей, яка може перетворювати цей текст у красиві документи. З цієї причини Markdown нині переживає період зростання популярності, не лише як засіб для написання наукових робіт, але й як усталений спосіб для онлайн-редагування загалом.
До популярних редакторів простого тексту загального призначення належать Atom (усі платформи) і Notepad++ (тільки Windows).
Важливо розуміти, що Markdown — це лише умовність. Файли розмітки зберігаються як звичайний текст, що ще більше збільшує гнучкість формату. Звичайні текстові файли існують з часів електронної друкарської машинки. Довговічність цього стандарту за своєю суттю робить звичайний текст більш стійким і стабільним, ніж власницькі формати. Хоча файли, створені навіть десять років тому в Microsoft Word і Apple Pages, можуть викликати значні проблеми при відкритті в останніх версіях цих редакторів. Хоча тексти написані у будь-якому “мертвому” редакторі звичайного тексту, на кшталт AlphaPlus , Perfect Writer, Text Wizard, Spellbinder, WordStar, все ще можливо відкрити. Написання простого тексту гарантує, що ваші файли залишатимуться читабельними через десять, п’ятнадцять, двадцять років. У цьому уроці ми описуємо робочий процес, який звільняє дослідника від власницьких текстових редакторів і крихких форматів файлів.
Сьогодні можна створювати широкий спектр документів в одному форматі — статті, публікації в блогах, вікі, навчальні плани та рекомендаційні листи — використовуючи той самий набір інструментів і методів для пошуку, виявлення, резервного копіювання та розповсюдження наших матеріалів. Ваші нотатки, записи в блозі, документація коду та вікі-сторінки – все це можна створювати в Markdown. Дедалі частіше багато платформ, як-от WordPress, Reddit і GitHub, підтримують авторство Markdown. У довгостроковій перспективі ваше дослідження виграє від таких уніфікованих робочих процесів, що полегшує збереження, пошук, спільний доступ і впорядкування ваших матеріалів. Markdown є зручним для роботи з AI, адже має просту й зрозумілу структуру. Його синтаксис легко сприймається як людьми, так і комп'ютерами, що робить формат придатним для автоматичної обробки. Завдяки цьому Markdown часто застосовують у штучному інтелекті, технічній документації та публікаціях.
Принципи
Натхненні передовим досвідом у різних дисциплінах, ми керувалися такими принципами:
Стійкість. Звичайний текст забезпечує прозорість і відповідає стандартам довгострокового збереження. MS Word може піти шляхом Word Perfect у майбутньому, але звичайний текст завжди залишатиметься легким для читання, каталогізації, копіювання та трансформації. Крім того, звичайний текст дозволяє легко та потужно створювати версії документа, що корисно для співпраці та організації чернеток. Ваші звичайні текстові файли будуть доступні на мобільних телефонах, планшетах або, можливо, на малопотужному терміналі в якійсь віддаленій бібліотеці. Звичайний текст має зворотну сумісність і перспективність. Незалежно від того, яке програмне чи апаратне забезпечення буде наступним, воно зможе зрозуміти ваші звичайні текстові файли.
Перевага для форматів, які відкриті для людини. Набираючи текст в Word або Google Docs, ви бачите не те, що отримуєте. Файл docx містить приховані автоматично згенеровані символи форматування, створюючи затуманений шар набору тексту, який користувачеві важко усунути. Щось таке просте, як вставлення зображення або тексту з браузера, може мати непередбачуваний вплив на форматування вашого документа.
Поділ форми і змісту. Одночасне написання та форматування відволікає. Ідея полягає в тому, щоб спочатку написати, а потім відформатувати, якомога ближче до етапу публікації. Таке завдання, як перехід від форматування Chicago до MLA, має бути безболісним. Редактори журналів, які хочуть заощадити час на непотрібне форматування та редагування копій, повинні мати можливість надати своїм авторам шаблон форматування, який подбає про дрібниці верстки.
Підтримка навчального апарату. Робочий процес має витончено обробляти виноски, малюнки, міжнародні символи та бібліографію.
Незалежність від платформи. Оскільки вектори публікацій різні, ми повинні мати можливість генерувати безліч форматів, зокрема для проекції слайдів, друку, Інтернету та мобільних пристроїв. В ідеалі ми хотіли б мати можливість створювати найпоширеніші формати, не порушуючи бібліографічних залежностей. Наш робочий процес також має бути портативним — було б чудово мати можливість скопіювати папку на флеш-накопичувач і знати, що вона містить усе, що потрібно для публікації. Написання простого тексту означає, що ви можете легко ділитися, редагувати та архівувати свої документи практично в будь-якому середовищі. Наприклад, навчальний план, написаний у Markdown, можна зберегти як PDF, роздрукувати як роздатковий матеріал і перетворити на HTML для Інтернету, усе з того самого файлу. І веб, і друковані документи мають бути опубліковані з одного джерела та виглядати однаково, зберігаючи логічне розташування матеріалу.
Markdown і LaTeX відповідають усім цим вимогам. Ми вибрали Markdown (а не LaTeX), тому що він пропонує найбільш легкий і позбавлений зайвого синтаксис, а також тому, що в поєднанні з Pandoc він забезпечує найбільшу гнучкість при конвертації у різні формати (включно з файлами docx і tex).
Вимоги до програмного забезпечення
Ми навмисне пропускаємо деякі деталі встановлення програмного забезпечення пов’язані з платформою чи операційною системою. Наприклад, немає сенсу надавати інструкції зі встановлення LaTeX, коли канонічні онлайн-інструкції для вашої операційної системи завжди залишатимуться актуальнішими та повнішими. Подібним чином механіку встановлення Pandoc найкраще досліджувати за пошуковим запитом "встановлення Pandoc" у Google, імовірно, першим результатом буде домашня сторінка Pandoc.
Редактор звичайного тексту. У світі редагування звичайного тексту перед вами постає значно ширший вибір інноваційних інструментів для його створення. Шукайте в Інтернеті "текстовий редактор" та експериментуйте зі знайденими редакторами. Немає значення, що використовувати, якщо це явно текстовий редактор, наприклад Atom або Notepad++. Пам’ятайте, оскільки ми не прив’язані до інструменту, ви можете будь-коли змінити ваш вибір на щось інше.
Термінал командного рядка. Робота "в командному рядку" еквівалентна введенню команд у термінал. На Mac вам просто потрібно скористатися пошуком для "terminal". У Windows використовуйте PowerShell. Користувачі Linux, швидше за все, вже знайомі зі своїми терміналами. Нижче ми розглянемо основи пошуку та використання командного рядка.
Pandoc. Детальні інструкції зі встановлення для конкретної платформи доступні на вебсайті Pandoc. Встановлення Pandoc на вашому комп’ютері має вирішальне значення для цього уроку, тож не поспішайте та прогляньте інструкції. Pandoc був створений і підтримується Джоном Макфарлейном, професором філософії Каліфорнійського університету в Берклі. Це цифрова гуманітаристика в найкращому вигляді, яка слугуватиме двигуном нашого робочого процесу. За допомогою Pandoc ви зможете компілювати текст і бібліографію в красиво відформатовані та гнучкі документи. Виконавши інструкції зі встановлення, переконайтеся, що Pandoc інстальовано, ввівши
pandoc --versionу командному рядку. Ми припускаємо, що у вас принаймні версія 3.1.3, випущена в жовтні 2024 року. На малюнку нижче наведений приклад для операційної системи Linux.
Наступні дві частини програмного забезпечення є рекомендованими, але не є обов’язковими для виконання цього заняття.
Zotero або Endnote. Бібліографічні довідкові програми, такі як Zotero та Endnote, є незамінними інструментами для організації та форматування цитат у науковій статті. Ці програми можуть експортувати ваші бібліотеки як файл BibTeX (про який ви дізнаєтеся більше у прикладі 2 нижче). Цей файл є форматованим текстовим документом усіх ваших цитат, дозволить вам швидко та легко цитувати посилання за допомогою тегів @. Слід зазначити, що також можна ввести всі ваші бібліографічні посилання вручну, використовуючи нашу бібліографію як шаблон.
LaTeX. Детальні інструкції зі встановлення для конкретної платформи доступні на вебсайті Pandoc. Хоча LaTeX не розглядається в цьому уроці, Pandoc використовує його для створення документів у форматі PDF. Досвідчені користувачі часто конвертують у LaTeX безпосередньо, щоб мати більш детальний контроль над набором PDF. Початківці можуть пропустити цей крок. В іншому випадку введіть
latex -v, щоб перевірити, чи LaTeX було встановлено правильно (ви отримаєте повідомлення про помилку, якщо вона трапилась, і деяку інформацію про версію, якщо її не було).
Основи Markdown
Markdown — це усталений спосіб для семантичного структурування ваших документів у вигляді звичайного тексту. Ідея полягає в тому, щоб ідентифікувати логічні структури у вашому документі (заголовок, розділи, підрозділи, виноски тощо), позначити їх деякими ненав’язливими символами, а потім "компілювати" отриманий текст за допомогою інтерпретатора верстки, який форматуватиме документ послідовно, відповідно до визначеного стилю.
Усталені практики щодо розмітки мають кілька "розмаїтостей", розроблених для використання в певних контекстах, таких як блоги, вікі або сховища коду. Версія Markdown, яку використовує Pandoc, призначена для академічного використання. Його умови описані на сторінці Pandoc Markdown. Його умовні позначення включають блок "YAML", який містить деякі корисні метадані.
Давайте тепер створимо простий документ у Markdown. Відкрийте редактор звичайного тексту за вашим вибором і почніть вводити текст. Це має виглядати так:
Markdown з елементами Pandoc зберігає кожне з наведених вище значень і "друкує" їх у відповідному місці вашого кінцевого документа, коли ви будете готові до набору. Пізніше ми навчимося додавати інші, потужніші поля до блоку YAML. Наразі давайте уявимо, що ми пишемо статтю, яка містить три розділи, кожен з яких поділений на два підрозділи. Залиште порожній рядок після останніх трьох дефісів у блоці YAML і вставте наступне:
Додайте будь-який текст, якій вам до вподоби. Порожній простір має важливе значення в Markdown: не робіть відступи в абзацах. Натомість розділяйте абзаци порожнім рядком. Порожні рядки також повинні передувати заголовкам розділів.
Ви можете використовувати зірочки, щоб додати жирний або курсив до своїх слів, наприклад: *курсив* і **жирний**. Ми також повинні додати посилання та виноску до нашого тексту, щоб охопити основні компоненти сторінки.
Коли текст посилання та адреса збігаються, простіше написати наприклад <www.eff.org> аніж [www.eff.org](www.eff.org)
Давайте збережемо наш файл, перш ніж рухатися далі. Створіть нову папку, у якій буде розміщено цей проєкт. Ймовірно, у вас є певна система організації ваших документів, проєктів, ілюстрацій і бібліографій. Але часто ваш документ, його ілюстрації та бібліографія знаходяться в різних папках, що ускладнює їх відстеження. Наша мета — створити єдину папку для кожного проєкту з усіма відповідними матеріалами. Загальне правило: один проєкт, один документ, одна папка. Назвіть свій файл markdown.md, де "md" означає розмітку.
На цьому етапі ваш markdown.md (ви можете завантажити зразок файлу тут) має виглядати приблизно так як зображено на малюнку.
Незабаром ми розберемось як цей простий текст можна конвертувати в різні формати, для прикладу так буде виглядати PDF створений з нашого з вами коду:
Якщо ви хочете отримати уявлення про те, як цей тип розмітки буде інтерпретуватися як форматування HTML, спробуйте цей онлайн-сервіс та проексперементуйте з різними видами синтаксису. Пам’ятайте, що певні елементи Markdown у зв’язці з Pandoc (наприклад, блок заголовка та виноски) не працюватимуть у цій вебформі.
На цьому етапі вам слід витратити деякий час на вивчення інших функцій Markdown, як-от цитати (на які посилається символ >), списки маркерів, які починаються з * або -, дослівні розриви рядків, які починаються з | (корисно для поезії), таблиці та деякі інші функції, перелічені на сторінці розмітки Pandoc.
Зверніть особливу увагу на порожній простір і формат абзаців. Документація коротко визначає абзац як "один або кілька рядків тексту, за якими слідує один або більше порожніх рядків". Зверніть увагу, що "новий рядок розглядається як пробіли" і що "якщо вам потрібен жорсткий розрив рядка, поставте два або більше пробілів у кінці рядка". Найкращий спосіб зрозуміти, що це означає — експериментувати. Використовуйте режим попереднього перегляду редактора або просто запустіть Pandoc, щоб побачити результати своїх експериментів.
Перш за все, уникайте бажання форматувати. Пам’ятайте, що ви визначаєте смислові одиниці: розділи, підрозділи, акценти, виноски та рисунки. Навіть *курсив* і **жирний** у Markdown насправді не є позначками форматування, а вказують на різний рівень акценту. Форматування відбудеться пізніше, коли ви дізнаєтеся вимоги до публікації.
Існують програми, які дають попередній перегляд результату роботи з Markdown під час редагування звичайного текстового файлу, про що ми докладно розповідаємо нижче в розділі "Корисні ресурси". Деякі з них підтримують виноски, малюнки та бібліографію. Щоб скористатися всіма перевагами Pandoc, ми рекомендуємо вам використовувати прості текстові файли, які зберігаються локально на вашому комп’ютері.
Зв’язок із внутрішнім терміналом системи
Перш ніж ми зможемо конвертувати наш файл markdown.md в інші формати, нам потрібно зорієнтуватися в роботі командного рядка за допомогою програми терміналу вашого комп’ютера, що є єдиним (і найкращим) способом використання Pandoc.
Командний рядок є доволі зручним, коли ви до нього звикнете. Якщо ви вже знайомі з використанням командного рядка, можете пропустити цей розділ. Для інших важливо розуміти, що можливість безпосереднього використання терміналу командного рядка дозволить використовувати широкий спектр потужних дослідницьких інструментів, якими ви не могли б скористатися раніше, і може стати основою для більш складної роботи. Для цілей цього уроку вам потрібно вивчити лише кілька дуже простих команд.
Спочатку відкрийте вікно командного рядка. Якщо ви використовуєте macOS, відкрийте програму Terminal у каталозі "Applications/Utilities". У Windows ми рекомендуємо використовувати PowerShell або, для більш надійного рішення, інсталювати підсистему Windows для Linux і використовувати термінал, який постачається з вашим улюбленим дистрибутивом Linux. Щоб отримати чудовий вступ до командного рядка, перегляньте урок "Знайомство з командним рядком Bash".
У терміналі ви повинні побачити текстове вікно та підказку, яка виглядає приблизно так:
Тильда вказує на ваш "домашній" каталог, і насправді ви можете ввести cd ~ у будь-який момент, щоб повернутися до домашнього каталогу. Не вводьте знак долара, він просто символізує командний рядок вашого терміналу, спонукаючи вас ввести щось у вашому терміналі ; не забудьте натиснути Enter після кожної команди.
Введіть pwd (показати робочий каталог) і натисніть Enter, щоб відобразити назву поточного каталогу. Використовуйте pwd щоразу, коли ви відчуваєте що загубились.
Команда ls (список), яка просто перераховує файли в поточному каталозі. Нарешті, ви можете використовувати cd> (змінити каталог), наприклад cd DIRECTORY_NAME (де DIRECTORY_NAME — це ім’я каталогу, до якого ви хочете перейти). Ви можете використовувати cd .. для автоматичного переходу на один рівень вище в структурі каталогу (батьківського каталогу папки, у якій ви зараз перебуваєте). Коли ви почнете вводити назву каталогу, використовуйте клавішу Tab, щоб автоматично завершити текст — особливо корисно для довгих імен каталогів або імен каталогів, які містять пробіли.
Ці три команди терміналу: pwd, ls і cd — це все, що вам потрібно для цього заняття. Попрактикуйтеся в них протягом кількох хвилин, щоб орієнтуватися у папці документів і подумати про те, як ви впорядкували свої файли. Якщо хочете, використовуйте звичайний графічний файловий менеджер, щоб орієнтуватися.
Використання Pandoc для перетворення Markdown на документ MS Word
Тепер ми готові до верстки! Відкрийте вікно терміналу, використовуйте pwd і cd DIRECTORY-NAME, щоб перейти до потрібної папки для вашого проєкту. Коли ви вже там, введіть ls у терміналі, щоб отримати список файлів. Якщо ви бачите свій файл markdown.md і зображення, ви перебуваєте в правильному місці. Щоб конвертувати .md у .docx, введіть:
pandoc markdown.md -o markdown.docxВідкрийте файл за допомогою MS Word, щоб перевірити результати. Крім того, якщо ви використовуєте Open- або LibreOffice, ви можете конвертувати наш файл у відповідний формат, виконавши таку команду:
pandoc markdown.md -o markdown.odtЯкщо ви новачок у командному рядку, уявіть, що ви читаєте наведену вище команду як щось на зразок: "Pandoc, створи файл MS Word із мого файлу Markdown". Частина -o є "прапорцем або опцією", яка у цьому випадку говорить щось на кшталт "замість того, щоб я прямо повідомляв вам вихідний і цільовий формати файлів, просто вгадайте, дивлячись на розширення файлу". Використовуючи такі опції ви зможете контролювати конвертацію файлів Markdown. Ви можете переглянути повний список опцій на вебсайті Pandoc або ввівши man pandoc у терміналі.
Спробуйте виконати команду:
pandoc markdown.md -o project.htmlТепер поверніться до каталогу проєкту. Ви можете сказати, що сталося?
Досвідченіші користувачі, які встановили LaTeX (або користувачі операційних систем OS X/Linux/Unix, де цей пакет вже встановлений), можуть поекспериментувати, перетворивши Markdown у файли tex або спеціально відформатовані файли pdf. Після встановлення LaTeX красиво відформатований PDF-файл можна створити за допомогою тієї самої командної структури:
pandoc markdown.md -o markdown.pdfЯкщо виконання цієї команди не вдасться, вам може знадобитися додати компонент, який надає Pandoc повний шлях до механізму LaTeX, який ви бажаєте використовувати, вказуючи, де він зберігається. Розташування буде різним залежно від того, чи працюєте ви на OS X, Windows чи Linux. Читачам радимо перевірити правильний шлях до двигуна LaTeX у своїй системі та слідувати поточним інструкціям зі встановлення.
Якщо ваш документ написаний не англійською мовою, вам, імовірно, доведеться використовувати механізм XeLaTeX замість звичайного LaTeX для перетворення в pdf:
pandoc markdown.md --pdf-engine=xelatex -o markdown.pdfПереконайтеся, що ваш текстовий редактор підтримує кодування UTF-8. Використовуючи XeLaTeX для перетворення у pdf, замість атрибута fontfamily у YAML для зміни шрифтів укажіть атрибут mainfont, щоб отримати щось на зразок такого:
Також, стилі шрифтів можна передати до Pandoc безпосередньо через командну стрічку терміналу:
pandoc --pdf-engine=xelatex markdown.md -V mainfont="Ubuntu Light.ttf" -o markdown.pdfОднак ми вважаємо за краще використовувати параметри заголовка YAML, коли це можливо, оскільки це полегшує введення довгих команд у вікні терміналу. Використання інструменту контролю версій, такого як Git, збереже ваші зміни YAML, де те, що ви вводите в терміналі, є більш ефемерним. Зверніться до розділу Templates (Шаблони) в уроці Pandoc (man pandoc), щоб отримати список доступних змінних YAML.
На закінчення цієї секції хочемо ще раз наголосити про використання шрифтів, які підтримують кирилицю. Користувачі операційної системи Windows не будуть мати ніяких проблем при конвертації Markdown тексту в PDF. В той час користувачі операційних систем OS X, UNIX чи Linux повинні контролювати цей процес і впевнитись, що вони використовують правильний шрифт. Для зручності ви можете використати шрифт Ubuntu-Light.ttf який ми використали сьогодні під час створення PDF файлу. Лише завантажте його в ваш робочий каталог, де розташований Markdown текст.
Робота з бібліографією
У цьому розділі ми додамо бібліографію до нашого документа, а потім конвертуємо з формату Chicago у формат MLA.
Якщо ви не використовуєте довідковий менеджер, як-от Endnote або Zotero, варто звернути на них увагу. Ми віддаємо перевагу Zotero, тому що, як і Pandoc, він був створений академічною спільнотою і, як і інші проєкти з відкритим вихідним кодом, випущений під загальною публічною ліцензією GNU. Найважливішим для нас є те, що ваш довідковий менеджер повинен мати можливість створювати бібліографії у форматі звичайного тексту відповідно до нашого принципу "все у звичайному тексті". Відкрийте довідковий менеджер за вашим вибором і додайте кілька зразків записів. Коли ви будете готові, знайдіть можливість експортувати свою бібліографію у формат BibTeX (bib) (універсальний формат створення списків цитувань для різних бібліографічних стилів). Збережіть файл з розширенням bib у каталозі проєкту та дайте йому назву, наприклад "project.bib" (зразок файлу можна завантажити тут).
Загальна ідея полягає в тому, щоб ваші джерела були організовані в одній централізованій бібліографічній базі даних, водночас створюючи специфічні та набагато менші файли bib, які зберігатимуться в тому самому каталозі, що й ваш проєкт. Відкрийте файл bib за допомогою редактора простого тексту на ваш вибір.
Ваш файл bib має містити кілька записів, які виглядатимуть приблизно так:
Вам рідко доведеться редагувати їх вручну. У більшості випадків ви просто "експортуєте" файл bib із Zotero або подібного довідкового менеджера. Знайдіть хвилинку, щоб зорієнтуватися в записі. Кожен запис складається з типу документа, у нашому випадку "стаття", унікального ідентифікатора (ioe_school_2024) і відповідних метаданих про назву, том, автора тощо. Найбільше нас цікавить унікальний ідентифікатор, який слідує за фігурною дужкою в першому рядку кожного запису. Унікальний ідентифікатор – це те, що дозволяє нам зв’язати бібліографію з основним документом. Наразі залиште цей файл відкритим і давайте повернемось до нашого файлу markdown.md.
Давайте додамо виноску в Секції 2.1 нашого файлу markdown.md так, як показано на малюнку.
Параметр [@ioe_school_2024, 1] містить унікальний ідентифікатор з нашої бібліографії project.bib.
Щойно ми запустимо наш markdown текст через Pandoc, "@ioe_school_2024" буде розгорнуто до повної цитати у стилі, який ви виберете. Ви можете використовувати синтаксис @citation будь-яким способом, який вважаєте за потрібне: у тексті чи у виносках. Щоб створити бібліографію, просто додайте розділ під назвою bibliography в кінці блоку YAML:
Це директива для Pandoc шукати нашу бібліографію у файлі project.bib у тому самому каталозі, що й файл markdown.md. Давайте перевіримо, чи це працює. Збережіть файл, перейдіть у вікно терміналу та виконайте команду:
pandoc --pdf-engine=xelatex markdown.md --citeproc -o markdown.pdfОпція "citeproc" проаналізує будь-які теги цитування, знайдені у вашому документі. У результаті має вийти пристойно відформатований файл PDF. Якщо у вас встановлено MS Word, конвертуйте у docx, використовуючи той самий синтаксис, щоб отримати кращі результати. Не хвилюйтеся, якщо все не зовсім так, як вам подобається — пам’ятайте, що ви зробите остаточне налаштувати форматування ближче до часу публікації. Наразі ми лише створюємо чернетки на основі базових стандартних налаштувань. На малюнку нижче наведено приклад такої конвертації у формат PDF:
Зміна стилів цитування
Типовим стилем цитування в Pandoc є Chicago Author-date. Ми можемо вказати інший стиль, використовуючи таблицю стилів, написану "Мовою стилю цитування" (ще одне правило для опису стилів цитування) і позначену розширенням файлу csl. На щастя, проєкт CSL підтримує сховище загальних стилів цитування, деякі навіть адаптовані для конкретних журналів. Відвідайте цей сайт, щоб знайти файл csl для Modern Language Association, завантажте modern-language-association.csl і збережіть його в каталозі проєкту як mla.csl (зразок файлу можна завантажити тут). Тепер нам потрібно сказати Pandoc використовувати таблицю стилів MLA замість Chicago за замовчуванням. Ми робимо це, оновлюючи заголовок YAML:
Знову виконайте команду в терміналі:
pandoc --pdf-engine=xelatex markdown.md --citeproc -o markdown.pdfі дослідіть як змінився стиль цитування. Коли ви ближче познайомитесь із таблицями стилів цитування, подумайте про те, щоб створити ваші спеціальні файли csl для журналів у вашій галузі.
Підсумок
Тепер ви зможете писати статті в Markdown, створювати чернетки в різних форматах, додавати бібліографії та легко змінювати стилі цитування. Останній перегляд каталогу проєкту покаже ряд "вихідних" файлів: ваш файл markdown.md, файл project.bib, файл mla.csl, Ukraine.jpg і шрифт, що підтримує кирилицю Ubuntu-Light.ttf. Окрім вихідних файлів, ви маєте побачити кілька "цільових" файлів, які ми створили під час навчання: markdown.docx або markdown.pdf. Ваша папка має виглядати приблизно так:
Ставтеся до своїх вихідних файлів як до авторських версій свого тексту, а цільові файли – як одноразові шаблони, які згодом ви зможете легко створити за допомогою Pandoc. Усі зміни мають виконуватись у файлі markdown.md. Файл main.docx призначений для остаточного форматування. Наприклад, якщо для журналу потрібні рукописи з подвійним інтервалом, ви можете швидко зробити подвійний пробіл у Open Office або Microsoft Word. Але не витрачайте надто багато часу на форматування. Пам’ятайте, що все це видаляється, коли ваш рукопис надходить у друк. Час, витрачений на непотрібне форматування, можна використати з більшою користю для шліфування тексту вашої чернетки.
Корисні ресурси
Якщо у вас виникнуть проблеми, немає кращого місця для пошуку підтримки, ніж сайт Pandoc Джона Макфарлейна та пов’язаний з ним сервіс розсилки. Також наступні два сайти формату "Запитання та відповіді", де ви можете запитати щодо Pandoc це: Stack Overflow і Digital Humanities Q&A. Запитання також можна ставити на Freenode IRC, каналі #Pandoc, який підтримує дружня компанія постійних користувачів. Коли ви дізнаєтесь більше про Pandoc, ви також зможете дослідити одну з його найпотужніших функцій: фільтри.
Попри те, що ми пропонуємо почати з простого редактора, багато інших (понад 70), специфічних Markdown альтернатив пакету MS Word, доступні онлайн і часто безкоштовно. З автономних нам сподобалися Mou, Write Monkey і Sublime Text. Існує кілька вебплатформ, які надають зручні графічні інтерфейси для спільного написання та відстеження версій за допомогою Markdown. Серед них: prose.io, Authorea, Draft і StackEdit.
Але екосистема не обмежується редакторами. Gitit та Ikiwiki підтримують створення в Markdown з Pandoc як парсери. До цього списку можна віднести ряд інструментів, які створюють швидкі статичні вебсторінки: Yst, Jekyll, Hakyll і сценарій оболонки bash від історика Калеба МакДеніела.
Нарешті, навколо використання Markdown формуються цілі видавничі платформи. Markdown на ринковій платформі Leanpub може стати цікавою альтернативою традиційній моделі публікації. І ми самі експериментуємо з дизайном академічних журналів на основі GitHub і readthedocs.org (інструменти, які зазвичай використовують для технічної документації).
Про авторів
Денніс Тенен, доцент кафедри англійської мови та порівняльного літературознавства Колумбійського університету. Грант Вітхофф, викладач кафедри англійської мови та порівняльного літературознавства Колумбійського університету.
Переклад українською: Дмитро Марченко, кандидат технічних наук, завідувач кафедри картографії та геопросторового моделювання Національного університету "Львівська політехніка".
Переклад рецензували: Кирило Осінський, Senior Software Engineer, Cheil Germany GmbH, LivArch Fellow. Олександр Косован, викладач Факультету прикладних наук, Український католицький університет.
Рекомендоване цитування: Тенен, Денніс, Вітхофф, Грант. "Публікація чистого тексту з допомогою Pandoc і Markdown", переклав Дмитро Марченко, Посібник з цифрової історії, 2025.
Last updated