Комментарии 15
Занятно :)
Спасибо за статью!
Использование docker'а здесь выглядит как из пушки по комарам или автор хотел блеснуть эффективным использованием контейнерной визуализации в сочетании с современной ИТ модой. Применение встроенного модуля в CPython venv на мой взгляд намного проще и понятнее, а так же не придётся набирать длинные команды вроде docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
Ведь даже стандартная документация к Питону генерируется с помощью venv без всяких контейнеров.
Поверьте, автор не хотел ничем блеснуть =)
Просто, не являясь практикующим питонистом, я всего лишь воспользовался наиболее подходящим вариантом из предложенного разработчиками material for mkdocs в их документации.
Поэтому благодарю за интересное предложение!
Наверное, можно предложить и разработчикам mkdocs добавить такой вариант прямо на страницу getting started - а не только сослаться на подобный метод в одном из абзацев раздела troubleshooting-а.
UPDATE. Более подробное изучение темы показало, что venv будет менее удобен при наличии зависимостей от не python библиотек.
Например, использование того же плагина with-pdf требует наличия в системе пакетов pango, для русского языка ttf-ubuntu-font-family, а также некоторых других (полный список есть в статье) - и вот это всё придётся всё равно ставить в основную систему.
А в случае докера это всё-таки можно "спрятать" в образ.
Все наглядно и подробно описано, спасибо!
Генераторов статики - мягко говоря дофига.
а вот интересно как во всё эот великолепие добавить картинки?
я бы мог предполодить что рядом с markdown документами могут лежать файлики и на них ставятся ссылки... но по крайнем мере в описании все примеры уводят в сетевые урлы
Спасибо за вопрос!
Вы абсолютно правы: картинки можно как hfcgjkfufnрасполагать рядом с файлом markdown, так и определять в отдельные папки, прописывая при этом в самом markdown относительные пути.
Я предпочитаю класть картинки в подпапку ./images.
Посмотрите пример в нашем репозитории https://gitlab.com/Rostelecom-IT/help-camera-rt/-/tree/master/desktop-app/docs/application_modes:
В файле index.md есть, к примеру, ссылка на картинку shortcut_internet_mode.png, расположенную в подпапке images. И вот как выглядит добавление картинки в самом файле:
Интересно есть возможность в html вставить маркдаун, чтобы было?
<div>
!!! note
…
</div>
При наличии JavaScript - разумеется есть. Поищите: в интернете есть несколько проектов конвертеров md -> html.
Лично мне чисто по описанию понравился https://github.com/showdownjs/showdown. Его можно использовать как в бэкенде (node.js), так и прямо в браузере. Примеры есть в самом репозитории.
Спасибо.
Как то сильно наворочено городить. Нашёл вариант проще.
markdown = "1" в открывающем HTML теге оказалось достаточно.
Вы не сталкивались с тем, что возможностей маркдауна не хватает для создания полноценных документов? Например, невозможно создавать хоть сколько-нибудь сложные таблицы. Или у вас используется какой-то расширенный маркдаун, который умеет больше базового?
Пошаговая инструкция как использовать MkDocs для создания сайта с документацией продукта