Как использовать pandoc для конвертации файлов в командной строке Linux

Ты можешь использовать pandoc в Linux конвертировать между более чем 40 форматами файлов. Вы также можете использовать его для создания простой системы документов как код, написав в Markdown, сохранив в gitи публикации в любом из поддерживаемых форматов.

Преобразование документов и Документы как код

Если у вас есть документ в любом из pandoc's много поддерживаемых форматов файлов, преобразование его в любой из других является легким. Это удобный инструмент, чтобы иметь!

Но настоящая сила pandoc становится очевидным, когда вы используете его как основу простой системы документов в виде кода. Предпосылка docs-as-code состоит в том, чтобы принять некоторые из методов и принципов разработки программного обеспечения и применить их к написанию документации, особенно для проектов разработки программного обеспечения. Вы можете применить его к разработке любой документации, однако.

Разработчики программного обеспечения используют свой любимый редактор или интегрированная среда разработки (IDE) для написания своих программ. Код, который они вводят, сохраняется в текстовых файлах. Они содержат исходный код для программы.

Они используют система контроля версийили VCS (Гит является наиболее популярным), чтобы фиксировать изменения в исходном коде по мере его разработки и улучшения. Это означает, что у программиста есть полная история всех версий файлов исходного кода. Он или она может быстро получить доступ к любой предыдущей версии файла. Git хранит файлы в репозитории. На компьютере каждого разработчика имеется локальный репозиторий и центральный общий удаленный репозиторий, который часто размещается в облаке.

Когда они готовы выпустить рабочую версию программы, они используют компилятор прочитать исходный код и сгенерировать двоичный исполняемый файл.

Написав свои документы на легком текстовом языке разметки, вы можете использовать VCS для контроля версий вашего письма. Когда вы будете готовы распространять или публиковать документ, вы можете использовать pandoc генерировать столько разных версий вашей документации, сколько вам нужно, включая веб-интерфейс (HTML), обработанный или набранный (LibreOffice, Microsoft Word, TeX), переносимый формат документа (PDF), электронная книга (EPUB), и так далее.

Вы можете сделать все это из одного набора облегченных текстовых файлов с управлением версиями.

Установка пандока

Установить pandoc в Ubuntu используйте эту команду:

sudo apt-get install pandoc

В Fedora вам нужна следующая команда:

sudo dnf install pandoc

На Манджаро нужно набрать:

sudo pacman -Syu pandoc

Вы можете проверить, какая версия установлена, используя --version опция:

pandoc --version

Использование pandoc без файлов

Если вы используете pandoc без каких-либо параметров командной строки, он также принимает типизированный ввод. Вы просто нажимаете Ctrl + D, чтобы указать, что вы закончили печатать. pandoc ожидает, что вы наберете в формате Markdown, и он генерирует вывод HTML.

Давайте посмотрим на пример:

pandoc

Мы набрали несколько строк Markdown и собираемся нажать Ctrl + D.

Как только мы это сделаем, pandoc генерирует эквивалентный вывод HTML.

Чтобы сделать что-нибудь полезное с pandocТем не менее, нам действительно нужно использовать файлы.

Основы уценки

Markdown – это легкий язык разметки, и определенным символам придается особое значение. Вы можете использовать простой текстовый редактор для создания файла Markdown.

Markdown может быть легко прочитан, поскольку нет визуально громоздких тегов, которые отвлекают от текста. Форматирование в документах Markdown напоминает форматирование, которое оно представляет. Ниже приведены некоторые из основ:

• Чтобы подчеркнуть текст с курсивЗаверните в звездочки. *This will be emphasized*
• к смелый текст, используйте две звездочки. **This will be in bold**
• Заголовки представлены знаком числа / хэш-меткой (#). Текст отделяется от хеша пробелом. Используйте один хеш для заголовка верхнего уровня, два для второго уровня и так далее.
• Чтобы создать маркированный список, начните каждую строку списка со звездочки и вставьте пробел перед текстом.
• Чтобы создать нумерованный список, начните каждую строку с цифры, за которой следует точка, а затем вставьте пробел перед текстом.
• Чтобы создать гиперссылку, заключите название сайта в квадратные скобки ([]) и URL в скобках[[()]вот так: [Link to How to Geek](https://www.howtogeek.com/),
• Чтобы вставить изображение, введите восклицательный знак непосредственно перед скобками (![]). Введите любой альтернативный текст для изображения в скобках. Затем заключите путь к изображению в скобках[[()«], Вот пример: ![The Geek](HTG.png),

Мы рассмотрим больше примеров всего этого в следующем разделе.

СВЯЗАННЫЙ: Что такое уценка и как вы ее используете?

Преобразование файлов

Преобразование файлов является простым. pandoc обычно можно определить, с какими форматами файлов вы работаете, по их именам. Здесь мы собираемся сгенерировать файл HTML из файла Markdown. -o (выходной) параметр говорит pandoc имя файла, который мы хотим создать:

pandoc -o sample.html sample.md

Наш образец файла Markdown, sample.md, содержит короткий раздел Markdown, показанный на рисунке ниже.

Файл с именем sample.html создан. Когда мы дважды щелкнем по файлу, наш браузер по умолчанию откроет его.

Теперь давайте создадим Открытый формат документа текстовый документ, который мы можем открыть в LibreOffice Writer:

pandoc -o sample.odt sample.md

Файл ODT имеет то же содержимое, что и файл HTML.

Аккуратное прикосновение – это альтернативный текст для изображения, который также используется для автоматического создания подписи к рисунку.

Указание форматов файлов

-f (от) и -t (для) варианты используются, чтобы сказать pandoc какие форматы файлов вы хотите конвертировать из и в. Это может быть полезно, если вы работаете с форматом файла, который имеет расширение файла с другими соответствующими форматами. Например, TeX, и Латекс оба используют расширение «.tex».

Мы также используем -s (автономный) вариант так pandoc создаст всю преамбулу LaTeX, необходимую для того, чтобы документ был полным, автономным и правильно сформированным документом LaTeX. Без -s (автономный вариант), результат будет по-прежнему правильно сформированным LaTeX, который может быть вставлен в другой документ LaTeX, он не будет правильно обрабатываться как отдельный документ LaTeX.

Мы вводим следующее:

pandoc -f markdown -t latex -s -o sample.tex sample.md

Если вы откроете файл «sample.tex» в текстовом редакторе, вы увидите созданный LaTeX. Если у вас есть редактор LaTeX, вы можете открыть файл TEX, чтобы увидеть предварительный просмотр интерпретации команд набора текста LaTeX. Уменьшение окна, чтобы соответствовать изображению ниже, сделало дисплей тесным, но на самом деле все было хорошо.

Мы использовали редактор LaTeX под названием Texmaker, Если вы хотите установить его в Ubuntu, введите следующее:

sudo apt-get install texmaker

В Fedora команда выглядит так:

sudo dnf install texmaker

В Манджаро используйте:

sudo pacman -Syu texmaker

Преобразование файлов с помощью шаблонов

Вы, вероятно, начинаете понимать, что гибкость pandoc обеспечивает. Вы можете написать один раз и опубликовать практически в любом формате. Это большой подвиг, но документы выглядят немного ванильно.

С помощью шаблонов вы можете определять, какие стили pandoc использует, когда он генерирует документы. Например, вы можете сказать pandoc использовать стили, определенные в Каскадные таблицы стилей (CSS) файл с --css вариант.

Мы создали небольшой файл CSS, содержащий текст ниже. Это изменяет интервал выше и ниже уровня заголовка на один стиль. Он также меняет цвет текста на белый, а цвет фона на синий:

h1 {
  color: #FFFFFF;
  background-color: #3C33FF;
  margin-top: 0px;
  margin-bottom: 1px;
}

Полная команда приведена ниже – обратите внимание, что мы также использовали автономную опцию (-s):

pandoc -o sample.html -s --css sample.css sample.md

pandoc использует единственный стиль из нашего минималистского CSS-файла и применяет его к заголовку первого уровня.

Другой вариант точной настройки, который вы можете использовать при работе с файлами HTML, – это включить разметку HTML в ваш файл Markdown. Это будет передано в сгенерированный файл HTML как стандартная разметка HTML.

Этот метод должен быть зарезервирован для случаев, когда вы генерируете только вывод HTML. Если вы работаете с несколькими форматами файлов, pandoc будет игнорировать HTML-разметку для файлов, отличных от HTML, и будет передана им в виде текста.

Мы также можем указать, какие стили используются при генерации ODT-файлов. Откройте пустой документ LibreOffice Writer и настройте стили заголовка и шрифта в соответствии со своими потребностями. В нашем примере мы также добавили верхний и нижний колонтитулы. Сохраните ваш документ как «odt-template.odt».

Теперь мы можем использовать это как шаблон с --reference-doc опция:

pandoc -o sample.odt --reference-doc=odt-template.odt sample.md

Сравните это с примером ODT из ранее. Этот документ использует другой шрифт, имеет цветные заголовки и включает верхние и нижние колонтитулы. Однако он был сгенерирован из того же самого файла «mark.md» Markdown.

Шаблоны справочных документов могут использоваться для обозначения различных этапов производства документа. Например, у вас могут быть шаблоны с водяными знаками «Черновик» или «Для проверки». Шаблон без водяного знака будет использоваться для окончательного документа.

Создание PDF-файлов

По умолчанию, pandoc использует движок LaTeX PDF для создания PDF-файлов. Самый простой способ убедиться, что вы удовлетворяете соответствующим зависимостям LaTeX, – это установить редактор LaTeX, такой как Texmaker.

Это довольно большая установка – и Tex, и LaTeX довольно здоровенные. Если пространство на вашем жестком диске ограничено, или вы знаете, что никогда не будете использовать TeX или LaTeX, вы можете создать файл ODT. Затем вы можете просто открыть его в LibreOffice Writer и сохранить в формате PDF.

Docs-а-код

Существует несколько преимуществ использования Markdown в качестве языка письма, включая следующие:

• Работать в текстовых файлах быстро: Они загружаются быстрее, чем файлы текстового процессора одинакового размера, и, как правило, быстрее перемещаются по документу. Многие редакторы, в том числе gedit , Vim , и Emacs, используйте подсветку синтаксиса с текстом Markdown.
• У вас будет график всех версий ваших документов: Если вы храните свою документацию в VCS, например в Git, вы можете легко увидеть различия между любыми двумя версиями одного и того же файла. Тем не менее, это действительно работает только тогда, когда файлы представляют собой простой текст, как это то, что VCS ожидает работать с.
• VCS может записывать, кто внес какие-либо изменения и когда: Это особенно полезно, если вы часто сотрудничаете с другими в крупных проектах. Он также предоставляет центральное хранилище для самих документов. Многие облачные сервисы Git, такие как GitHub, GitLab, и BitBucket, есть бесплатные уровни в своих моделях ценообразования.
• Вы можете создавать свои документы в нескольких форматах: С помощью пары простых сценариев оболочки вы можете использовать стили из CSS и справочных документов. Если вы храните свои документы в хранилище VCS, которое интегрируется с Непрерывная интеграция и непрерывное развертывание (CI / CD) платформы, они могут генерироваться автоматически при сборке программного обеспечения.

СВЯЗАННЫЙ: Что такое GitHub и для чего он используется?

Последние мысли

Есть много других опций и возможностей внутри pandoc чем то, что мы рассмотрели здесь. Процессы преобразования для большинства типов файлов можно настроить и настроить. Чтобы узнать больше, ознакомьтесь с прекрасными примерами на официальном (и чрезвычайно подробном) веб-страница pandoc,