NV
Size: a a a
2018 December 04
NV
Экспериментировать очень удобно в этой песочнице на гитлабе. Форкаете проект, редактируете, гитлаб сам собирает и публикует на gitlab-pages. t.me/docops/6
M
У меня в некоторой степени похожая проблема - есть куча документов в формате .md, какими инструментами можно их публиковать в формате статических веб страниц.
Пошарил по staticgen, выбор богатый)
Остановился на Docusaurus https://www.staticgen.com/docusaurus
Но прежде делать окончательный выбор хотел бы спросить, может кто сталкивался с похожей задачей и если да то какими инструментами решали?
Пошарил по staticgen, выбор богатый)
Остановился на Docusaurus https://www.staticgen.com/docusaurus
Но прежде делать окончательный выбор хотел бы спросить, может кто сталкивался с похожей задачей и если да то какими инструментами решали?
СФ
тогда предлагаю вам выбрать SSG по таким критериям:
— написан на языке, на котором у вас есть разработчики. Вот Руби вам именно этим не подходит, да?
— из коробки есть тема (шаблон) оформления, которая вам нравится
— написан на языке, на котором у вас есть разработчики. Вот Руби вам именно этим не подходит, да?
— из коробки есть тема (шаблон) оформления, которая вам нравится
по-моему, это очень исчерпывающий ответ
СФ
формальных требования же только два — брать на вход md и отдавать на выход HTML
СФ
остальные два персонализированных ограничения @Nick_Volynkin правильно описал
NV
остальные два персонализированных ограничения @Nick_Volynkin правильно описал
я эти ограничения выстрадал )
СФ
в остальном все SSG плюс-минус одинаковые
a
У меня в некоторой степени похожая проблема - есть куча документов в формате .md, какими инструментами можно их публиковать в формате статических веб страниц.
Пошарил по staticgen, выбор богатый)
Остановился на Docusaurus https://www.staticgen.com/docusaurus
Но прежде делать окончательный выбор хотел бы спросить, может кто сталкивался с похожей задачей и если да то какими инструментами решали?
Пошарил по staticgen, выбор богатый)
Остановился на Docusaurus https://www.staticgen.com/docusaurus
Но прежде делать окончательный выбор хотел бы спросить, может кто сталкивался с похожей задачей и если да то какими инструментами решали?
Мы используем Jekyll, без плагинов. Написали свою тему + включения (includes). Прикрутили lunr.js, mermaid.js, reveal.js, anchor.js все в min. Сжимаем html, sass, mercurial, билдим, публикуем на свой сервер.
NV
в остальном все SSG плюс-минус одинаковые
таки есть отличия. При прочих равных можно брать то, у чего больше звёзд на гитхабе )
NV
Потому что в нём (вероятно) быстрее добавляют фичи и правят баги.
TZ
MM
Hanna
Задача — найти инструмент для красивой API документации. Наткнулась на вот такой проект https://github.com/lord/slate, выглядит красиво, но смущает генератор на ruby, и что "нативная" совместимость только с github pages. Было бы здорово узнать, есть ли успешные кейсы применения middleman на реальных проектах с публикацией документации, например, через docker контейнер. Потому что если нет, то скорее всего будет нецелесообразно лезть разбиираться 🙂
Привет, недавно начали использовать Slate. Буду про него рассказывать на митапе в positive technologies.
MM
Тоже хочу соединить его со swagger, но пока ещё нет
NV
Hanna вот вам ещё хороший доклад о том, как выстроить разработку документации с такими инструментами https://2018.secrus.org/program/submitted-presentations/developing-documentation/
NV
Привет, недавно начали использовать Slate. Буду про него рассказывать на митапе в positive technologies.
О, хоть кто-то из нашей секты будет там. 🙂 А я уж думал, будут одни CMS'ки соревноваться.
H
тогда предлагаю вам выбрать SSG по таким критериям:
— написан на языке, на котором у вас есть разработчики. Вот Руби вам именно этим не подходит, да?
— из коробки есть тема (шаблон) оформления, которая вам нравится
— написан на языке, на котором у вас есть разработчики. Вот Руби вам именно этим не подходит, да?
— из коробки есть тема (шаблон) оформления, которая вам нравится
всё упёрлось в шаблон оформления, не смогла найти ничего лучше, чем у slate. изначально SSGs на питоне смотрела
H
Hanna вот вам ещё хороший доклад о том, как выстроить разработку документации с такими инструментами https://2018.secrus.org/program/submitted-presentations/developing-documentation/
обязательно посмотрю, спасибо)
NV
А как вы определяете «лучше»?
H
шаблон, в котором справа от описания параметров можно разместить пример кода. например, как здесь: https://stripe.com/docs/api