Вопрос или проблема
У меня есть набор связанных markdown файлов. Я хотел бы создать формат, похожий на книгу, или HTML, или PDF. Я искал и нашел 3 инструмента:
Какие функции я ищу:
- Совместимые расширения Chrome/Chromium, которые позволят мне копировать содержание веб-сайта и вставлять его в конечный формат (markdown имеет эту возможность)
- Я использую VS Code для написания своих заметок в markdown файлах, мне хотелось бы поддержка утилиты сборки для автоматизации рендеринга markdown. Поскольку я продолжаю добавлять новые markdown файлы на лету, может быть, утилита сборки сможет генерировать обновленный блокнот, скажем, каждые 15 минут.
- Мои заметки имеют более сложную структуру, чем просто несколько уровней подкаталогов, поэтому утилита сборки должна иметь возможность рекурсивно добавлять все файлы (порядок, в котором файлы должны добавляться, может быть определен номером, указанным в заголовке yaml файла).
- Хотя мне не важно платить за программное обеспечение, было бы хорошо иметь самые дешевые инструменты.
Если вы пользовались этими инструментами, можете порекомендовать мне подходящий инструмент (пожалуйста, подтвердите это сравнением плюсов и минусов)?
Лично я бы предложил обратить внимание на Sphinx-Doc, который является инструментом документации на Python, использующим ReStructuredText (с поддержкой Markdown), для создания красивой документации в разных форматах, всех с перекрестными ссылками, встроенными изображениями и т.д.:
- HTML Веб-сайт (поиск)
- HTML Помощь
- PDF Документ
- eBook
Функции включают:
- Иерархическая структура
- Генерация оглавления
- Генерация индекса или индексов
- Сноски
- Глоссарии
- Внешние ссылки
- Код с подсветкой синтаксиса (для более чем 80 языков программирования).
- Хорошая интернационализация.
- Автоматическая генерация на readthedocs.org из репозиториев GitHub.
- Несколько HTML тем в стандартной установке & вы можете настроить или скачать больше (даже темы, удобные для мобильных устройств).
- Степень контроля над генерацией PDF.
- Отображение математических формул (с помощью расширений).
- Скрипт Make может быть связан с макросом в VS Code
- Все инструменты являются:
- Бесплатными (Gratis)
- Бесплатными (Open Source)
- Кросс-платформенными (Windows/OS-X/Linux/Прочие)
Встроенные темы:
Ответ или решение
Вопрос объединения коллекции файлов Markdown в книгу представляет собой интересную задачу, которая может быть эффективно решена с использованием различных инструментов. В вашем случае вы уже рассматривали три популярных решения: Pandoc, GitBook и Bookdown. Ниже представлена подробная информация о каждом из них, а также рекомендации по выбору, исходя из ваших требований.
1. Pandoc
Pandoc — мощный инструмент для конвертации документов, который поддерживает множество форматов, включая Markdown, HTML, PDF, EPUB и многие другие.
Преимущества:
- Поддержка множества форматов: Pandoc может конвертировать Markdown в другие форматы, такие как HTML и PDF.
- Гибкость: С помощью пользовательских скриптов вы можете автоматизировать процесс сборки и настройки файлов.
- Поддержка расширений: Вы можете добавлять пользовательские метаданные и данные для настройки вывода.
Недостатки:
- Кривая обучения: Из-за большого количества опций и настроек может потребоваться время для освоения.
- Нет встроенной функции планировщика: Вам нужно будет написать скрипт для автоматической сборки.
2. GitBook
GitBook популярное решение для создания документации и книг на основе Markdown.
Преимущества:
- Интуитивно понятный интерфейс: Позволяет легко писать и редактировать книги в веб-интерфейсе.
- Поддержка командной работы: Удобно для совместной работы над проектами.
- Генерация книг в разных форматах: Поддержка экспортирования в PDF и ePub.
Недостатки:
- Онлайн-платформа: Некоторые функции доступны только в платном тарифе.
- Проблемы с локальной работой: Если вы предпочитаете писать без интернет-соединения, это может стать ограничением.
3. Bookdown
Bookdown — это пакет для R, который позволяет создавать книги из файлов R Markdown.
Преимущества:
- Идеален для статистических и научных публикаций: Подходит для анализа данных и создания научных работ.
- Гибкость в структурировании файлов: Легко управлять вложенностью и порядком файлов через YAML заголовки.
- Поддержка кросс-ссылок и таблиц: Отлично подходит для создания документации с высоким уровнем детализации.
Недостатки:
- Необходимость установить R и другие зависимости.
- Доступен больше для научных проектов: Возможны ограничения для других типов контента.
4. Sphinx
Sphinx — это инструмент для создания документации, который поддерживает как reStructuredText, так и Markdown. Он хорош для создания технической документации и может генерировать PDF, HTML и EPUB.
Преимущества:
- Поддержка структуры и индексов: Может автоматически генерировать оглавления и индексы.
- Создание документации с хорошей поддержкой: Имеет множество расширений для улучшения функциональности.
- Автоматическая генерация: Легко настраивается для использования с системами контроля версий.
Недостатки:
- Имеет некоторую кривую обучения: Может потребоваться время на освоение, особенно для пользователей, не знакомых с Python.
- Требует настройки конфигурационных файлов.
Рекомендации
Для вашего сценария, учитывая, что вы используете VS Code и хотите автоматизировать сборку, я рекомендовал бы Pandoc в сочетании с пользовательскими скриптами для автоматизации процесса компиляции, либо Sphinx, если вас интересует более структурированная документация.
Заключение
Исходя из ваших требований, можно выделить, что Sphinx и Pandoc предлагают наибольшую гибкость и функциональность для создания книг из Markdown файлов. В конечном итоге, выбор инструмента будет зависеть от ваших навыков и структуры контента, с которым вы работаете. Рекомендуется протестировать несколько инструментов, чтобы определить, какой из них наиболее подходит для вашего рабочего потока.