Комментарии 46
2. Ctrl-C > Ctrl-V в новый редактор хабра
3. Исправить места с поехавшим форматированием
4. Поматериться на общую кривокосость нового редактора
5. Отправить пачку новых косяков и утешить себя тем, что доделают же его когда-то
6. Опубликовать
Когда из этого алгоритма уйдут пункты 4 и 5, жить станет намного приятней, чем держать пачку конвертеров и проверяльщиков наконверченного.
У меня процесс выглядит так:
- использую github pages для своего сайта со статейками
- к себе на сайт пишу черновик RU/ENG(вобще это обычно расшировки выступлений своих)
- расскидываю ссылки заинтересованным, правлю.
- копирую на хабр как есть. приходится подправлять url картинок и хабракат добавлять
такую схему уже года 3 использую
Тоже недавно задумался над тем, как улучшить написание в маркдауне :) Остановился на VsCode и плагинах к нему. Из неупомянутых выбрал:
- Markdown All in One
- Spell Right — для win8+ и mac словари используются системные
- Prettier — Code formatter
Скажите, а конвертирующий скрипт что делает с оглавлением? Хабр обычное markdown-оглавление не понимает, насколько помню, надо вручную ссылки делать.
Лично я пишу в Емаксе в режиме org-mode, откуда экспортирую в Github Markdown при помощи pandoc, после чего правлю всякую ерунду небольшим макросом.
Я генерирую оглавление с помощью плагина Markdown TOC в VSCode, об этом также писал в статье. Но есть и другие плагины.
А MarkConv конвертирует относительные ссылки из обычного формата в формат хабра. Например, #генерация-оглавления преобразуется в #generaciya-oglavleniya. На примере этой статьи видим, что оглавление работает :) А в репозитории MarkConv есть и тесты.
Ага, понял, как раз этого фокуса (конвертации ссылок) в статье и нет.
Может, стоит добавить пояснение? Мало ли, кто будет что-то подобное делать другими инструментами, или будет в ваше решение вникать.
В любом случае спасибо!
Вообще немножко есть в абзаце Конвертируем:
Есть и другие различия: реализация спойлеров, внутренних ссылок и.т.д;
Но я вас понял: подумаю над тем, чтобы подробней это расписать.
Я вообще свой Хабр сделал на гитхабе: https://github.com/nin-jin/habhub
До хабра это не дотягивает. Использовать GitHub, но набирать статьи в issues — странное решение — они для этого не предназначены, т.к. отсутствует версионирование. Почему бы просто не писать статьи в формате md и хранить их в репозитории?
Чтобы была возможно комментирования. Но на гитхабе уже появились дискуссии. Надо будет попробовать их.
Ну так можно при создании поста просто создавать новую issue для комментариев.
Руками это делать не удобно. Да и удобней, когда комменты сразу под постом.
Что-нибудь вроде https://github.com/utterances-bot — не вариант?
Моя мечта чтобы люди перешли с Confluence на markdown и писали документацию через коммиты.
Я все материалы пишу в GoogleDocs — на панели закладок всегда есть ссылка на новый док. Это не только даёт уверенности, что он не потеряется (в Хабре несохранённый черновик лежит в localStorage и может потеряться, а с локальным редактором/ноутбуком тоже может что-нибудь случиться), но и позволяет оперативно что-то коллективно поправить (или согласовать). Второе многим авторам Хабра не нужно, но для меня это уже часть процесса — показать коллеге, которая всегда что-то по существу добавит-поправит. Да, гугл на днях прилёг, но это скорее исключение, ни разу такого не встречал больше. Также любую статью легко найти через поиск в аккаунте.
Картинки вставляю прямо в гугл-документ, уже оптимизированные (обычно 1500px, несмотря на то, что в Хабре контентная часть 780). Затем всё это выделяю, копирую и вставляю в этот конвертер — он выдаёт код поста, которому нужно минимум правок.
А далее, важный момент: вставляю код из конвертера в черновик на Хабре и сохраняю его — в результате этого картинки автоматом заливаются на Хабрасторож. То есть и в самом документе гугла были картинки (для наглядности) вместо текстовых пометок 123.jpg, и возиться с их заливкой не нужно. Получившийся код подходит и для блога, где как раз пригождаются картинки большого размера )
Если вам не нужно коллективное редактирование, то новый редактор вполне комфортный для написания материала или размещения. Хотя всегда есть что доработать.
В gitlab достаточно удобный markdown редактор, хотя и есть отличия от хабровского формата, но не значительные, можно пометить просто перед публикацией пофиксить.
Поэтому можно редактировать так:
- Создать репу в гитлабе (закрытую, если хотите).
- Набрать статью.
- Вычитать, проверить орфографию.
- Дать вычитать знакомому (в отдельной ветке, он может каждое исправление как коммит делать)
- Мерж.
- Скопировать в хабр и пройтись по форматированию.
PS: набирать статью можно хоть в самом gitlab, хоть в VSCode, хоть в Intellij IDEA
Word не поддерживает нормальное версионирование с помощью git, а значит коллективная работа над статьей ограничена. Кроме того, файл docx весит больше чем md, содержит больше служебных элементов, сложнее в обработке. Редактора Word нет под Linux (есть LibreOffice, но это не то).
Где ваш плагин можно взять поиграться?
У нас много совместной работы с документами, поэтому был разработан специальный конвертер, но вот чтоб мы чувствовали ограничение от коллекстивной работы — не было такого.
Был период, когда можно было внести изменения в нашу работу, я смотрел на md, но так и не понял, куда деть картинки. Сейчас они запакованы в .docx. Каталог с документами выглядит удобным и понятным. Как бы вы хранили картинки, если они используются в нескольких тысячах документов?
Код нашего плагина закрыт, т.к. это только малая часть всей внутренней «кухни» по управлению документами в компании.
У Word есть встроенное версионирование, которое запускается диффером Git или SVN. Очень редко пользуемся.
Но какой от него толк, если на условном GitHub оно все равно не будет работать через браузер.
У нас много совместной работы с документами, поэтому был разработан специальный конвертер, но вот чтоб мы чувствовали ограничение от коллекстивной работы — не было такого.
У разработчиков гитхаба тоже много совместной работы с документами, тем не менее они используют Markdown и Git для документации на https://github.com/github/docs.
Как бы вы хранили картинки, если они используются в нескольких тысячах документов?
Как и сейчас — внутри репозитория, доступ к одной картинке может быть из нескольких документов. Как и в данной статье — ее можно открыть оффлайн. При конвертации используется информация из тегов linkmap — об этом написано в статье. В теории загрузку картинок на внешний сервис тоже можно автоматизировать, но не всегда есть доступ к API сервиса с изображениями. Но можно и сразу использовать картинки с внешнего сервиса без возни с мэппингом.
Код нашего плагина закрыт, т.к. это только малая часть всей внутренней «кухни» по управлению документами в компании.
Ну тогда особо смысла в вашем решении в контексте данной статьи нет — оно не предназначено для массового пользователя.
А как вообще в md решают вопрос с картинками? Скажем, если тексты редактируются оффлайн, но выкладываются на Хабр/Dropbox Paper/еще что-нибудь (и наоборот), то картинки все равно придется подтягивать вручную по одной?
Я считаю это не удобным при локальном хранении и редактировании. А в случае сайта/форума с редактором md меня, например, не беспокоит, где хранятся картинки и как они версионируются.
Если нет требования к автономности, то картинки можно хранить на том же habrastorage. Если есть — то вместе со статьей и мэппить их на картинки с внешнего сервиса при публикации.
Пишу личные заметки, статьи, веду базу знаний именно по приведённой схеме — md + git, очень удобно.
Проблем у меня две.
Одна — с картинками, очень хочется такого, как в современных cms-системах когда достаточно бросить картинку из файла или просто из буфера обмена в браузер и тебе её автоматом на лету вставят-сохранят как надо, я бы очень приветствовал если бы такое в vscode появилось.
Вторая — с diff'ом таблиц. Ну, такое. Вероятно, надо просто перестать рассматривать эти diff'ы и не париться, это думаю чистейшей воды профдеформация: есть люди, которые вставляют текст из ворда в cms'ку и не парятся насколько ужасная под капотом разметка (кто видел вордовские стили — тот поймёт), а есть те, кто при этом руками выправляет теги. И вот деформация в том, что я отношусь скорее к людям второго типа, поэтому по-возможности полусознательно избегаю вставки таблиц ибо геморрой.
Одна — с картинками, очень хочется такого, как в современных cms-системах когда достаточно бросить картинку из файла или просто из буфера обмена в браузер и тебе её автоматом на лету вставят-сохранят как надо, я бы очень приветствовал если бы такое в vscode появилось.
Сейчас попробовал расширение Paste Image — вставлять картинки из буфера оно умеет. Но есть и другие расширения.
Вторая — с diff'ом таблиц. Ну, такое.
А вы пробовали описывать таблицы с помощью html тегов? Это поддерживаются и в VSCode и на Хабре.
<table>
<tr>
<td>column 1</td>
<td>column 2</td>
</tr>
</table>Возможно их диф будет больше радовать ваши глаза.
А кто корректирует и редактирует? Судя по требованию создавать issue и пулл реквесты — другие программисты. Но когда этим занимаются не программисты, а редакторы — объяснить им, что надо делать пул реквесты решительно невозможно. Даже предложение редактироват не ворд, а непонятно что с их точки зрения выглядит идиотским.
В ворде ведь и удобно подсвечиваются правки и можно сразу поправить документ, а не передавать правки автору, чтобы он их применил. И выглядит этот документ нормально, а не как птичий язык.
Есть редакторы, которые понимают и принимают Markdown и Git. В чатах https://t.me/technicalwriters и https://t.me/docsascode таких немало (за что им спасибо, что вызвались помочь с вычиткой).
Есть редакторы, которые понимают и принимают Markdown и Git.
Получается, что в разработанную вами систему нужно интегрировать какого-то такого редактора, а это товар штучный. С одной стороны это большой недостаток, но с другой стороны, если все будут делать что-то такое, может станет больше таких редакторов )).
В VSCode или Atom есть прекрасные плагины для работы со стандартным markdown. Стандартный markdown принимается очень много где — на GitHub, в каждой второй системе генерации документации, в каждой IDE / текстовом редакторе.
Поэтому возникает вопрос — ради написания статей и документации, зачем множить сущности? Уже скорее уж хабру надо подстроиться под общепринятые стандарты. А поправить пару косяков (даже и в новом редакторе) — не проблема.
Конечно если нет цели писать статьи по КД или заниматься virtue signalling-ом.
Это надо у разработчиков хабра спрашивать, зачем они собственный Markdown изобрели. Благодаря конвертеру, вы как раз и сможете работать со стандартным gfm.
Что касается дополнительных тегов include, linkmap — их использовать не обязательно. Первый — когда требуется включить контент из другого файла, второй — если нужно отобразить локальные ресурсы на удаленные (в основном картинки). При рендере стандартного Markdown такие теги просто игнорируются (как и хабровский cut).
У вас фигурные скобки не сбалансированы.
Интересно, а почему вы просто не добавили в pandoc ещё один формат?
Хороший вопрос.
Вряд ли такое изменение примут непосредственно в проект — все-таки хабр не очень популярный. Во всяком случае мою issue в 2017 по поводу формата CodeProject отклонили:
Too special-purpose. I recommend simply postprocessing the HTML, a perl one-liner will suffice.
Я не знаю Haskell;
Но есть и другой вариант интеграции — использовать pandoc фильтры, но:
- pandoc не дампит точную позицию AST в исходнике, а это критично, поскольку важно понимать позицию ошибки, чтобы можно было ее исправить. Хотя в следующей версии такая фича вроде должна появиться: https://github.com/jgm/pandoc/issues/4565;
- Не учитываются HTML элементы, т.е. для HTML кода просто создаются RawBlock, в моем же конвертере для корректно обработки тегов используется HTML парсер. Впрочем, это касается и используемого в текущий момент Markdown парсера;
- На момент старта я не знал о фильтрах;
- pandoc — дополнительная зависимость.
Но вообще есть идея попробовать заюзать pandoc со следующей версии, чтобы поддерживать намного больше языков, а не только Markdown.
Когда у меня возикла проблема с хабровским маркдауном я сделал форк pandoc, скопипастил модуль для маркдауна и сделал нужныне мне изменения. Хаскел я тоже не знаю, но всё оказалось не так уж сложно.
Я правда не обновлял свой форк уже лет 5, но мне хватает. Если интересно немного подробностей, например, что знание Хаскела не так уж и нужно, можно посмотреть вот этот коммит https://github.com/poxu/pandoc/commit/b6dc432cb3c128be67692d53b41cb3aebc0340bf
Насколько я понял, в вашем форке добавлена только склейка строк, но этого и так можно добиться с помощью опции --wrap=none. Для корректной конвертации относительных ссылок и спойлеров нужно побольше кода.
Насколько я понял, в вашем форке добавлена только склейка строк, но этого и так можно добиться с помощью опции --wrap=none.
Огромное спасибо за подсказку. То ли не было этой опции в pandoc тогда, то ли я не нашёл.
Для корректной конвертации относительных ссылок и спойлеров нужно побольше кода.
У меня в статьях по-моему считай нет относительных ссылок и спойлеров. Но я тут подумал, возможно это потому что их неудобно делать.
Ваш пример впечатляет и вдохновляет. Я пишу статьи в org-mode и потом конвертером преобразую к нужному формату. Создаётся впечатление, что ваша разработка сделана как раз для таких как я.
Я пишу статьи в org-mode и потом конвертером преобразую к нужному формату. Создаётся впечатление, что ваша разработка сделана как раз для таких как я.
Пробуйте на здоровье — баги можно репоритить в репозиторий или даже предлагать пулл-риквесты. Я старался реализовать как можно более простое взаимодействие с конвертером, и сейчас требуется только один обязательный параметр, имя input файла, все остальные "настройки" описываются в самой статье, а не через параметры командной строки (как было раньше).
Статьи — это тоже исходный код {