Обоснование
Я занимаюсь преподаванием в техническом ВУЗе. И для меня это не основная работа — прежде всего я инженер-программист. Как инженер, я стараюсь всё автоматизировать. Чтобы не повторяться на лекциях и практиках раз за разом, я пишу примеры и статьи для своих курсов.Есть ряд требований к формату моих примеров:
- Примеры кода должны иметь читаемый, прокомментированный в нужных местах код, понятный даже новичку в предметной области курса
- Но даже читаемого кода недостаточно: на каждый пример нужна статья-путеводитель
- В этой статье будет отполированный текст, схемы, иллюстрации и примеры кода.
- Стиль должен накладываться на уже готовый контент.
В конце концов я пришёл к Github-flavored Markdown. Работа с онлайн-редакторами Markdown быстро обескураживает, и встаёт вопрос выбора Offline-редактора.
ReText на Ubuntu
На Ubuntu после прочтения ряда отзывов я выбрал редактор ReText — открытое ПО, которое разрабатывается в репозитории на github.
Об этом редакторе есть хорошая статья на хабре: habrahabr.ru/post/161669
- Парсер редактора хорошо умеет работать в Github-совместимом режиме, и это большая редкость среди редакторов Markdown
- Есть live preview, который включается в меню редактора
- Есть публикация в ODT и PDF
- Есть поддержка расширений, которая позволяет включить подсветку кусков исходного кода в Preview документа, включить Table of Contents и другие подобные вещи. В сочетании с публикацией в PDF/ODT это часто работает неправильно.
- На заметку: я для себя перечислял через запятую расширения "codehilite" и "toc", которые после перезапуска редактора начинали работать.
- В сочетании с публикацией в PDF/ODT расширения часто работают неправильно.
- Live preview пока что посредственно работает с автоскроллингом: если вы редактируете текст, автоскроллинг preview может уйти куда-либо в сторону на сложных документах.
- Публикация в ODT реализована простым созданием объекта класса QTextDocument и записью его с помощью QTextDocumentWriter. В результате корректно генерируются только простые документы, а в сложных стили, подсветка кода или Table of Contents могут слететь, и даже простые маркеры списков экспортируются неправильно.
Пользователям Linux я бы посоветовал поставить версию из репозитория Github, а не из системных репозиториев. В этом случае вы встретите меньшее число недоработок.
Github Atom на любой платформе
Другой удобный вариант — это Github Atom, который обладает всеми плюсами предыдущего редактора (кроме разве что экспорта в ODT). Кроме того, Github Atom легко устанавливается на любой платформе, и имеет средства, например, для просмотра файловой структуры.
Несколько советов:
- Если вы набираете русский текст, то отключите в настройках встроенный плагин Spell Check. На момент написания этого поста плагин ищет ошибки только по английскому словарю, и безнадёжно подчёркивает красным цветом весь русскоязычный текст.
- В основной поставке атома уже есть поддержка Preview: хоткей "Ctrl+Shift+M"
- Есть сторонний пакет "markdown-scroll-sync", который качественно синхронизирует курсор в тексте и прокрутку preview документа
- Встроенный парсер Markdown может запросто сломаться на вставках исходного кода. Пакет "language-markdown" перегружает и улучшает встроенный парсер, исправляя его от поломок и добавляя подсветку вставок исходного кода.
Публикация на Github Pages
Сервис Github предоставляет хостинг статических сайтов, известный как Github Pages. Никакого бекенда — всё должно быть на Javascript (без XHR, т.е. без запросов на другие доменты), CSS и HTML. Правда, есть интеграция с генератором Jekyll, который превращает Markdown в HTML, а SCSS в CSS.
Если вы хотите развернуть свой сайт со статьями на Markdown, дам несколько советов:
- Jekyll написан на Ruby, и его проще развернуть на Linux или MacOSX, а не на Windows. Однако, знание Ruby вам едва ли потребуется.
- Будьте готовы испортить свой Markdown из-за заголовка, который вам придётся добавлять в каждую статью. В примере ниже свойство title можно и не ставить, а вот разделители "---" поставить придётся в любом случае, иначе Jekyll просто не будет обрабатывать весь файл:
--- title: 'UV-параметризация сферы' ---
- Чтобы запустить локальную версию сайта на http://localhost:4000/, запустите Jekyll в режиме веб-сервера командой "jekyll serve". Jekyll будет автоматически отслеживать изменения в каталоге проекта и перегенерировать файлы.
- Если вы хотите, чтобы ваши статьи имели обозначенный вами же preview в соцсетях, вы можете настроить интеграцию OpenGraph с Jekyll.
На сегодня у меня всё.