— Ямщик, а далеко до релиза?
— Да пара вёрсток.
Докатился — пишу на Хабр о том, как писать на Хабр. Хотя причины есть — я пять лет занимаюсь этим, перевидал и перепробовал кучу инструментов, так что теперь делюсь с вами самыми лучшими.
Я расскажу о том, как прийти от HTML-разметки в Хабраредакторе к осмысленной вёрстке, быстрому оформлению постов и продуктивной совместной работе. Здесь — о моём опыте в Яндекс.Деньгах и о том, как я организовал работу над хабратекстами, чтобы не было мучительно больно.
Стили — наше всё
Начну с не самой очевидной для такого поста вещи.
Стили — штука, которую я активно прививаю своим коллегам и студентам. Речь не об инфостиле или там научно-художественном, а о том, как ваш текст выглядит. Если вы однажды научитесь верстать стилями, обратного пути уже не будет. (В этом месте хитро хмыкнули LaTex-ребята — вы слишком крутые, дайте нам, простым смертным, позабавиться с оформлением.)
Меню, которым никто не знает, как пользоваться
Суть проста — вы оформляете кусок текста нужным образом, сохраняете шаблон и потом применяете его везде, где нужно. Этот шаблон в Word и Google Docs называется стилем. Студенты, которые верстали диплом стилями, на 90% счастливее тех, кто вручную менял шрифт, отступы и всё остальное у каждого абзаца и заголовка на ста страницах текста.
С Хабром всё, конечно, проще — достаточно понимать структуру своей статьи и расставлять заголовки нужного уровня. Разобраться с этим совсем просто — h1, h2, h3 и h4 — как в html.
Разберитесь с маркдауном
Если вы вдруг ещё не.
Markdown — сущность, которая пугала меня с тех пор, как появилась в хабраредакторе. Она выглядела как что-то вражеское и непохожее на привычные HTML-теги и полностью отталкивала от себя. Практика показала, что из двух вариантов лучше выбрать именно его.
Даже если вы пишете во встроенном редакторе хабра (хотя администрация и не рекомендует этого делать), markdown сэкономит вам кучу времени и сил. Хотя, конечно, лучше выберите другой инструмент. Хабраредактор годится для правильного предпросмотра, да и всё.
Markdown чуть-чуть отличается от случая к случаю. У Хабра markdown со своим вкусом — по ссылке понятное руководство, с которого точно стоит начать путь в мир отсутствия страдания при вёрстке хабрапостов.
Где писать?
Пишите там, где вам удобно. Единственное, что нужно помнить: удобно писать != удобно верстать для Хабра. Если вам удобен vim — продолжайте, а я расскажу о более консервативных способах писать тексты и о том, как они применимы на Хабре.
В Яндекс.Деньгах мы пишем по-разному — у разных авторов разные привычные текстовые редакторы, и я стараюсь не сильно их заставлять. Некоторые авторы присылают текстовые документы на Яндекс.Диске или по почте, другие пишут сразу в маркдауне или в сервисах для совместного редактирования.
Visual Studio Code (или Sublime)
Я пишу этот текст (и большинство других) в VS Code, сразу в маркдауне. Левая половина экрана — под текст, правая — отображение свёрстанного в Markdown текста через соответствующий плагин. Плагин называется Markdown MPE Preview — поддерживает загрузку картинок с компьютера на imgur и вставку ссылок в нужное место текста.
Пост-пост, мета-мета
Некоторые пишущие ребята могут меня осудить — дескать, Sublime Text 3 лучше. Точно знаю, что там тоже есть всякое для работы с маркдауном — пользуйтесь им, если вам удобнее. Ну и вообще, редакторов — десятки, если не сотни, под все платформы и на любой вкус. Главное, пишите хорошо :)
Microsoft Word
Если у вас есть компьютер на Windows, скорее всего, там установлен Word. И у ваших соавторов (если у вас есть соавторы), скорее всего, тоже. Это нормальный и привычный для большинства инструмент, хоть и платный.
Проблема в том, что в Word (если у вас нет королевской подписки) нельзя редактировать документы совместно, а значит, работа сведется к Черновик_Хабр_Тестирование_разработки_финальная_2_c_правками_от_начальника_3_заметкиPR.docx. Эта боль, насколько мне известно, преследует и некоторых дизайнеров, иллюстраторов и других «правочных» ребят.
Но даже это не так страшно. Основная беда в том, что без ритуальных плясок вы не будете видеть текст так, как он будет выглядеть на сайте. Сначала кажется, что в этом ничего страшного. Осознание катастрофы приходит после первых нескольких часов, потраченных на перенос текста из вордовского файла.
Честно говоря, мне неизвестно о каких-то публичных конвертерах из doc в markdown, который нормально примет Хабр. Не сомневаюсь, что они есть, но хабратексты Яндекс.Денег в Ворде если и пишутся, то только некоторыми авторами, а потом оперативно превращаются в маркдаун.
Google Docs
Общеизвестно отличная штука, еще и бесплатная. Максимально готова к совместной работе многих авторов, редакторов и остальных сочувствующих. Функциональности хватит на что угодно. Требует гугл-аккаунт, но у кого сейчас его нет?
В гугл-доке удобно работать, если несколько человек пишут разные части одного и того же текста — например, про работу платежных API на iOS и Android. Разные разработчики, разные блоки, абзацы, но все видят всё, и ничего никуда не потеряется. Отдельный плюс — история правок.
Здесь, как и в Word, достаточно расставить заголовки, и тогда при экспорте не придётся делать кучу лишней работы.
Минусы — если вы делитесь ссылкой на файл, то ей гораздо проще утечь куда-то не туда. Но если вы не пишете ничего, содержащего NDA, то и ничего страшного. Еще тут всё сложно с предварительным просмотром навёрстанного, но есть и плюсы — перенос текста из гугл-дока на хабр намного проще.
Что ещё бывает
Ещё есть невероятный мир текстов в txt-файлах с абзацными отступами в три-пять пробелов. По этическим причинам я не могу этого показать (мне и самому страшно открывать это), но поверьте — все варианты выше точно лучше.
Как ещё улучшить себе жизнь
Типограф
Ваш текст будет в сто раз лучше, если там будут стоять правильные кавычки, тире и исчезнут случайные двойные пробелы. Для этого есть типограф студии Лебедева — загрузите туда текст, и через секунду получите красивый результат.
Здесь проявляется еще один плюс маркдауна — если вы закинете целиком гугл-док или сверстанный вордовский файл в типограф, на выходе всё равно получите plain text. Картинки тоже потеряются. А с маркдауном проблемы нет — вёрстка генерируется после, а картинки стоят ссылками, поэтому можно это делать в любом количестве, успевай только жать Ctrl+A.
Конечно, это не отменяет необходимости проверки текста хорошим корректором. С другой стороны, если вы не пишете в корпоративные блоги и просто делитесь штуками на Хабре, то это хорошее подспорье в работе.
Хабраконвертеры
Текст из Google Docs можно переносить разными способами — руками или через разные конвертеры. Идеальный мне пока не попадался, поэтому обычно я совмещаю функциональность двух хороших.
Первый — https://shirixae.github.io/habraconverter-v2/. Скопируйте целиком гугл-док в текстовое поле — вот и всё. Он генерирует приличный Markdown, если вы не забыли расставить заголовки. Хорош ещё и тем, что выдергивает из гугл-дока ссылки на картинки — их, конечно, нужно перезалить на Habrastorage, но лучше, чем ничего.
Второй — расширение Docs To Markdown. Генерирует лучший markdown-код, хорошо работает с разрывами строк, но не умеет в картинки.
Почему это важно — если пять человек пишут текст с картинками, то оказывается довольно сложно получить от всех файлы, которые потом нужно отсортировать, разложить в верном порядке и опубликовать.
Конечно, если вы пишете сами и всё заботливо пронумеровано и разложено по папочкам, то просто заливайте на Habrastorage.
Когда редактирую текст нескольких авторов, делаю так — беру текст из второго конвертера, а картинки перезаливаю на Habrastorage по ссылкам из первого. Звучит не суперпросто, но экономит бесконечное количество времени.
Полезные советы про markdown и не только
- Разбивайте текст на абзацы. Пожалуйста!
- Картинки — на Habrastorage. Это очевидно, но лучше повторить. Нет ничего хуже, чем открыть полезный пост пятилетней давности и понять, что ссылки на картинки давно протухли. К слову, HS отдаёт готовые ссылки, обёрнутые в Markdown.
- В нумерации списков важен только первый элемент, остальные ставьте как угодно. Это полезно, если вы решили переставить местами элементы списка на 10 элементов, но лень менять цифры.
- Таблицы — картинками. В маркдауне весёлые таблицы, которые ломают мозг в первые несколько раз, но Хабр не умеет их красиво отображать — тексты в ячейках переносятся на новую строку. Лучше рисуйте их где-то ещё и вставляйте PNG.
upd. Хороший совет от opanas из комментов — «рядом с таблицей-картинкой желательно поместить спойлер (в котором таблица текстом будет — и копировать читатель сможет, и робот с индексированием справится)». - Новый гугл-док создаётся по ссылке doc.new — добавьте её на панель закладок, чтобы каждый раз экономить время.
- Храните черновики — синхронизируйте их с каким-нибудь облаком. Конечно, всегда можно достать вёрстку из публикации на Хабре, но, как показывает практика, так надёжнее.
- Отступы между заголовками разного уровня — самая случайная вещь в мире, по крайней мере, в первые 30 раз. Обязательно перепроверьте перед публикацией, что у вас в тексте нормальные отступы.
- HTML, перемешанный с хабра-маркдауном, может создавать забавные баги в сторонних редакторах. Например, если вы используете тег
<code/>и забыли его правильно закрыть. Получится вот такое:
Выводы
Все приведенные в этом посте советы взяты из личного опыта. Они только помогут сэкономить время и нервы на дополнительной работе, которую нужно проделать при подготовке поста — и написание интересного текста никто не отменял.
Практика показывает, что если вам интересно писать о чём-то, вас не остановят ни вёрстка, ни html, ни сложности конвертирования. Вы успешно зальете все картинки, расставите руками заголовки и теги, оформите код, и пост всё равно получится хорошим — потому что, очевидно, текст важнее оформления. Но никто не мешает сделать красиво и порадовать читателей. А значит, нужно делать.
Так победим.
Комментарии (57)
little-brother
13.03.2019 10:28+1У markdown имеются проблемы с расстановкой строк: если использовать спойлер или список, то элементы располагаются сильно удаленно. Также, как и на github, хотя markdown и можно с обычным html смешивать, но он может ломаться в самый неподходящий момент.
В итоге приходится использовать обычный html.
evil_me Автор
13.03.2019 10:55Всё так, но они работают сильно специфически и как-то каждый раз по-разному.
В какой-то момент мы даже делали ненумерованные списки простым текстом с буллетами-тире, чтобы всё не расползалось.
Xop
13.03.2019 10:32+1Когда готовил свою статью — изначально писал в маркдауне, но при попытке опубликовать хабр обрезал чуть ли не половину. Однако методом тыка обнаружилось, что ровно то же количества текста в виде html отлично проходит. В итоге еще один лишний вечер на переверстку, и статью все-таки опубликовал, но осадок остался.
evil_me Автор
13.03.2019 10:40+1Такое бывает, если случайно прилепить абзац текста к концу списка или неаккуратно вставить разметку кода.
Заголовок смещается правее, а остаток текста пропадает вовсе, пока не разведешь их пустой строкой.
Мне кажется, это допустимый компромисс и дело привычки — как, например, запомнить, где в маркдауне картинка ![](), а где просто ссылка [](). Ну или как перекрасить заголовок в HTML-разметке — надо только чуть наловчиться.
Xop
13.03.2019 11:04Заголовок смещается правее, а остаток текста пропадает вовсе, пока не разведешь их пустой строкой.
Именно такого точно не было, возможно какой-то ещё кейс, но текст резало прямо в середине абзаца.
vconst
13.03.2019 10:39А у вас —
ус отклеилсядвойной дефис в тире не конвертируется.
Когда расскажете о продуктивной совместной работе? Или за это сойдет упоминание Гуглодокс и «беру текст из второго конвертера, а картинки перезаливаю»?
Arson
13.03.2019 10:56А почему Вы у себя в яндексе не используете документы яндекса? :)
evil_me Автор
13.03.2019 11:06Доставка статей от авторов редакторам устроена довольно демократично. В Яндекс.Диск, например, встроен Word Online — если коллегам нравится пользоваться им, а не standalone-версией, никто не запрещает.
BarakAdama
13.03.2019 11:20+1Вики — один из самых популярных внутренних инструментов для документов и статей. Лично я предпочитаю писать там, но свободу выбора инструмента никто не отменяет :-)
POS_troi
13.03.2019 12:23+1Ну и вообще, редакторов — десятки, если не сотни, под все платформы и на любой вкус.
На правах личного мнения, есть неплохой редактор MarkDown — Typora.
В принципе, функционал только и состоит из редактора и более ничего, умеет импотировать (конвертировать) из различных форматов в MarkDown но делает это через PanDoc и соответственно не всё там очень хорошо :)
Drag13
13.03.2019 13:14Ползуюсь VSCode + markdownlint + отдельный репозиторий на github для синхронизации. И удобно, и есть история, и habr более менее адекватно рендерит.
speshuric
13.03.2019 13:42+1Ещё один лайфхак. В gitlab есть встроенная web-IDE. Она умеет работать с md. Там же можно делать ревью, там же просматривать, там же редактировать, там же история правки в понятном любому разработчику виде. При этом ещё и редактировать можно в любимом редакторе. Там же можно временно хранить картинки. Ветки git, наверное, никому в такой задаче не приводятся, но они есть.
poxvuibr
13.03.2019 14:10С маркдауном у Хабра проблема в том, что он не склеивает строки. Поэтому приходится проходиться по статье, написанной в маркдаун ещё одним конвертером, который конвертит маркдаун в хабровский маркдаун.
KvanTTT
13.03.2019 17:31Это каким? Специально для этой цели разработал MarkConv. Помимо склеивания, он конвертит спойлеры, адреса картинок с локальных на habrastorage, относительные ссылки (удобно для содержания) и делает другие полезные вещи.
poxvuibr
14.03.2019 13:06Когда-то давно я сделал свой форк pandoc и добавил туда хабросовместимый html. Потом на хабре появился маркдаун и я стал склеивать строки вместо хабра каким-то ключиком в pandoc. Последние статьи у меня написаны в org-mode.
Но есть один нюанс — если ты работаешь над статьёй не один, а есть какой-то редактор или кто-то в этом духе, то никакого маркдауна и тем более оргмода нельзя. Надо выкладывать у гуглдоки, чтобы там все делали правки.
KvanTTT
14.03.2019 19:21Но есть один нюанс — если ты работаешь над статьёй не один, а есть какой-то редактор или кто-то в этом духе, то никакого маркдауна и тем более оргмода нельзя.
Можно конечно, для чего Git с GitHub существуют? Я бы даже сказал нужно. Одно из достоинств Markdown — простые дифы. К тому же разрывы строк как раз и существуют, чтобы вместо одной огромной измененной строки размером в абзац отображалась строка размером 80-120 символов.
poxvuibr
15.03.2019 09:19Всё вы правильно говорите, только редакторы не знают что такое Git и работать с ним, конечно, не умеют. Редакторы исправляют косноязычность, ошибки всякие и так дале, с их точки зрения инструмент для совместной работы над текстом это именно гуглдок. Да и, к сожалению, не только с их точки зрения, а с точки зрения вообще всех, кто не программист в широком смысле этого слова.
olegchir
13.03.2019 14:53Я начинал делать IDE для написания текстов на Хабр, но из-за нагрузки прекратил, и сейчас оно существует в виде набора полезных скриптов (которые очень заточены на мой ноутбук, и для отчуждения и превращения в удобный софт нужна значительная работа). В комментариях к этому комменту можно пожелать, какие фичи вы бы хотели видеть в такой IDE.
Newbilius
13.03.2019 15:15Прям IDE? o_O
Достаточно было бы WISIWIG, который отображает именно так, как отобразит хабр.olegchir
13.03.2019 15:40+1Бывали периоды, когда выпускал по одной хабростатье в день. А может и по нескольку, если считать помощь в вычитке другим авторам. Когда дрожащими руками делаешь перевод статьи на тридцать страниц, пытаясь успеть к концу дня, параллельно координируясь с автором, дизайнером, корректором и остальными — возникают совершенно специфические требования к удобству. Или например, если тебе нужно сделать статью по докладу, в котором 200 слайдов, которых у нас в блоге JUG.ru Group предостаточно. Это как хороший автомобиль, один раз в день в булочную можно съездить и на Оке, а вот целыми днями жить в Оке крайне не рекомендуется :-) В общем, это сложно объяснить словами, и это надо показывать пачку скриптов, написанных за последний год. Возможно, однажды я соберу их во что-то, что смогут использовать другие люди.
Meklon
13.03.2019 15:41Хм. А как бы из уже сверстанного HTML перегнать в Markdown?
evil_me Автор
13.03.2019 15:48По запросу «convert html to markdown» нашлось несколько конвертеров, но все они не прошли быстрый тест и посыпались на тексте с несколькими тегами <code/>. Дальше копать не стал.
Предполагаю, что быстрее всего переразметить готовый HTML руками, но был бы рад ошибаться.olegchir
13.03.2019 16:21Я юзаю эти кривые реверсеры, и потом допиливаю руками. Не видел ещё ни одного реверсера, который работал бы хоть сколько-то осмысленно хорошо. В последний раз юзал Reverse Markdown, в принципе жить можно.
KvanTTT
13.03.2019 17:53Я пишу статью на гитхабе в собственном репозитории Articles причем в GitHub формате Markdown (да, да, он существенно отличается от хабровского). С помощью своей утилиты MarkConv перегоняю их в формат хабра. Как уже писал ранее, он склеивает строки, конвертит спойлеры, меняет адреса картинок с локальных на habrastorage, преобразует относительные ссылки (удобно для содержания) и делает другие полезные вещи.
В связи с тем, что не так давно приватные репозитории стали бесплатными, можно создать приватный репозиторий для черновиков и паблик — для финальных опубликованных топиков. Пушить и туда и туда очень просто, т.к. это Git. Как следствие, получаем механизмы Issues, Pull Request, историю изменений, возможность бекапа локально или на другие сервисы.
Кстати, тоже планирую написать статью о том как писать статьи, но используя Git и GitHub (GitLab) и внешние IDE. Правда надо доделать до конца что запланировал.
KvanTTT
13.03.2019 17:55А использовать Google Docs для Markdown… Ну, если честно, не очень.
evil_me Автор
13.03.2019 18:40Писать в гугл-доке маркдаун неудобно, конечно. Поэтому пишется как обычно, заголовки размечаются встроенными стилями, а потом, когда все правки от всех заинтересованных внесены, документ конвертируется в маркдаун.
Wesha
13.03.2019 18:43Ёпрст, научите меня уже делать всплывающие подсказки на хабре (слово подчеркнуто пунктиром, при наведении мышой всплывает разъяснение) — а то перечитал стопицот документаций, а найти всё не могу и не могу!
evil_me Автор
13.03.2019 18:49Древние подсказывают, что это делается через ABBR.
abbr title="тэг Abbr">ABBR</abbrWesha
13.03.2019 18:56О величайший и мудрейший, а
в какой священной книге это написаносам-то как узнал? :)evil_me Автор
13.03.2019 18:59Ссылка на это чудо чудное была прямо в статье :)
https://habr.com/ru/info/topics/madskillz/
Danik-ik
13.03.2019 22:32+1Что-то на мобиле оно никак не смотрится… Или я просто не умею интуитивный интерфейс?
MinamotoSoft
13.03.2019 22:54-2Для того чтобы напИсать «идиот» следует вставить двойные апострофы (тогда они не отображаются) затем тире-пробле-тире (тоже не видно) затем альт+255+альт+255 и букву " И" (пробел — обязательно).
Примерно — так.
mwambanatanga
14.03.2019 08:171. Разбивайте текст на абзацы
..., но при этом не превращайте статью в распечатку чата, начиная каждое предложение с новой строки.
RustySword
14.03.2019 09:13На iPhone, iPad и MacBook использую Bear. Поддерживает и MD и HTML. Экспортирует так же в MD, HTML, TXT, DOCX, PDF и прочее. Моментально синхронизируется, что очень удобно, так как часто переключаюсь между девайсами.
Для предосмотра просто копирую в хабраэдитор.
valemak
>>> Таблицы — картинками
Крайне сомнительный совет.
Текст-картинка не проиндексируется должным образом поисковиками и статью не будут находить по ключевым словам из этой таблицы. И в поиске самого хабра по словам из таблицы статья тоже не будет попадать в выборку.
А подготовка такой картинки (сделать таблицу в другом редакторе, потом скриншотить её, затем в фотошопе уменьшать/увеличивать эту картинку по ширине с потерей качества изображения, вставлять картинку в текст с правильным обтеканием если таблица небольшая и т.п.) запросто может оказаться более геморройным делом, чем оформить таблицу в тексте с помощью html-тегов.
evil_me Автор
Я говорил скорее о том, что в некоторых таблицах столбцы превращаются в кашу, которую довольно сложно контролировать (а есть же еще мобильная версия сайта). Таким болеют и HTML, и markdown. Всё зависит от типа таблицы, и надо пробовать, прежде чем понять, выбрать для таблицы текст или картинку.
opanas
Я бы скорее дополнил совет тем, что рядом с таблицей-картинкой желательно поместить спойлер (в котором таблица текстом будет — и копировать читатель сможет, и робот с индексированием справится).
evil_me Автор
Спасибо, это хороший совет. Добавил в пост.
valemak
В целом атрибут width для ячеек нормально работает, что можно использовать как для большого так и малого количества текста в ячейках таблицы.
atomlib
<th width="100">Cool</th>.valemak
Именно так. Кроме того есть альтернативный способ, чтобы ширина ячеек с малым количеством текста не была слишком короткой.
