Пост-пост, мета-мета. Учимся писать на Хабр


    — Ямщик, а далеко до релиза?
    — Да пара вёрсток.


    Докатился — пишу на Хабр о том, как писать на Хабр. Хотя причины есть — я пять лет занимаюсь этим, перевидал и перепробовал кучу инструментов, так что теперь делюсь с вами самыми лучшими.


    Я расскажу о том, как прийти от 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 и не только


    1. Разбивайте текст на абзацы. Пожалуйста!
    2. Картинки — на Habrastorage. Это очевидно, но лучше повторить. Нет ничего хуже, чем открыть полезный пост пятилетней давности и понять, что ссылки на картинки давно протухли. К слову, HS отдаёт готовые ссылки, обёрнутые в Markdown.
    3. В нумерации списков важен только первый элемент, остальные ставьте как угодно. Это полезно, если вы решили переставить местами элементы списка на 10 элементов, но лень менять цифры.
    4. Таблицы — картинками. В маркдауне весёлые таблицы, которые ломают мозг в первые несколько раз, но Хабр не умеет их красиво отображать — тексты в ячейках переносятся на новую строку. Лучше рисуйте их где-то ещё и вставляйте PNG.
      upd. Хороший совет от opanas из комментов — «рядом с таблицей-картинкой желательно поместить спойлер (в котором таблица текстом будет — и копировать читатель сможет, и робот с индексированием справится)».
    5. Новый гугл-док создаётся по ссылке doc.new — добавьте её на панель закладок, чтобы каждый раз экономить время.
    6. Храните черновики — синхронизируйте их с каким-нибудь облаком. Конечно, всегда можно достать вёрстку из публикации на Хабре, но, как показывает практика, так надёжнее.
    7. Отступы между заголовками разного уровня — самая случайная вещь в мире, по крайней мере, в первые 30 раз. Обязательно перепроверьте перед публикацией, что у вас в тексте нормальные отступы.
    8. HTML, перемешанный с хабра-маркдауном, может создавать забавные баги в сторонних редакторах. Например, если вы используете тег <code/> и забыли его правильно закрыть. Получится вот такое:

    Выводы


    Все приведенные в этом посте советы взяты из личного опыта. Они только помогут сэкономить время и нервы на дополнительной работе, которую нужно проделать при подготовке поста — и написание интересного текста никто не отменял.


    Практика показывает, что если вам интересно писать о чём-то, вас не остановят ни вёрстка, ни html, ни сложности конвертирования. Вы успешно зальете все картинки, расставите руками заголовки и теги, оформите код, и пост всё равно получится хорошим — потому что, очевидно, текст важнее оформления. Но никто не мешает сделать красиво и порадовать читателей. А значит, нужно делать.


    Так победим.

    Яндекс.Деньги
    174,00
    Как мы делаем Деньги
    Поддержать автора
    Поделиться публикацией

    Комментарии 57

      +2
      >>> Таблицы — картинками

      Крайне сомнительный совет.

      Текст-картинка не проиндексируется должным образом поисковиками и статью не будут находить по ключевым словам из этой таблицы. И в поиске самого хабра по словам из таблицы статья тоже не будет попадать в выборку.

      А подготовка такой картинки (сделать таблицу в другом редакторе, потом скриншотить её, затем в фотошопе уменьшать/увеличивать эту картинку по ширине с потерей качества изображения, вставлять картинку в текст с правильным обтеканием если таблица небольшая и т.п.) запросто может оказаться более геморройным делом, чем оформить таблицу в тексте с помощью html-тегов.
        +1


        Я говорил скорее о том, что в некоторых таблицах столбцы превращаются в кашу, которую довольно сложно контролировать (а есть же еще мобильная версия сайта). Таким болеют и HTML, и markdown. Всё зависит от типа таблицы, и надо пробовать, прежде чем понять, выбрать для таблицы текст или картинку.

          +1
          Я бы скорее дополнил совет тем, что рядом с таблицей-картинкой желательно поместить спойлер (в котором таблица текстом будет — и копировать читатель сможет, и робот с индексированием справится).
            +2
            Спасибо, это хороший совет. Добавил в пост.
            +1
            В целом атрибут width для ячеек нормально работает, что можно использовать как для большого так и малого количества текста в ячейках таблицы.

              +1
              в некоторых таблицах столбцы превращаются в кашу, которую довольно сложно контролировать
              Легко: <th width="100">Cool</th>.
                +1
                Именно так. Кроме того есть альтернативный способ, чтобы ширина ячеек с малым количеством текста не была слишком короткой.

            +2
            У markdown имеются проблемы с расстановкой строк: если использовать спойлер или список, то элементы располагаются сильно удаленно. Также, как и на github, хотя markdown и можно с обычным html смешивать, но он может ломаться в самый неподходящий момент.
            В итоге приходится использовать обычный html.
              0

              Всё так, но они работают сильно специфически и как-то каждый раз по-разному.
              В какой-то момент мы даже делали ненумерованные списки простым текстом с буллетами-тире, чтобы всё не расползалось.


              +2
              Когда готовил свою статью — изначально писал в маркдауне, но при попытке опубликовать хабр обрезал чуть ли не половину. Однако методом тыка обнаружилось, что ровно то же количества текста в виде html отлично проходит. В итоге еще один лишний вечер на переверстку, и статью все-таки опубликовал, но осадок остался.
                +1

                Такое бывает, если случайно прилепить абзац текста к концу списка или неаккуратно вставить разметку кода.



                Заголовок смещается правее, а остаток текста пропадает вовсе, пока не разведешь их пустой строкой.


                Мне кажется, это допустимый компромисс и дело привычки — как, например, запомнить, где в маркдауне картинка ![](), а где просто ссылка [](). Ну или как перекрасить заголовок в HTML-разметке — надо только чуть наловчиться.

                  0
                  Заголовок смещается правее, а остаток текста пропадает вовсе, пока не разведешь их пустой строкой.

                  Именно такого точно не было, возможно какой-то ещё кейс, но текст резало прямо в середине абзаца.

                0
                А у вас — ус отклеился двойной дефис в тире не конвертируется.
                Когда расскажете о продуктивной совместной работе? Или за это сойдет упоминание Гуглодокс и «беру текст из второго конвертера, а картинки перезаливаю»?
                  0
                  двойной дефис в тире не конвертируется

                  Это делает Типограф.

                    +1
                    Его и Хабр сейчас автоматически конвертирует во время рендера страницы. Но мы, по старинке, и через Типограф прогоняем.
                      0

                      И правда. Странно, что в справке Хабра не упомянуто.

                  0
                  изображение установить по центру возможно?
                    +1
                    В HTML вот так:

                    <img align=center src="картинка">
                      0
                      А текст вот до сих пор нельзя. Это нужно для подписей под картинками и в таблицах.
                      +3
                      А почему Вы у себя в яндексе не используете документы яндекса? :)
                        0
                        Доставка статей от авторов редакторам устроена довольно демократично. В Яндекс.Диск, например, встроен Word Online — если коллегам нравится пользоваться им, а не standalone-версией, никто не запрещает.
                          +3
                          Вики — один из самых популярных внутренних инструментов для документов и статей. Лично я предпочитаю писать там, но свободу выбора инструмента никто не отменяет :-)
                          +3
                          Ну и вообще, редакторов — десятки, если не сотни, под все платформы и на любой вкус.

                          На правах личного мнения, есть неплохой редактор MarkDown — Typora.
                          В принципе, функционал только и состоит из редактора и более ничего, умеет импотировать (конвертировать) из различных форматов в MarkDown но делает это через PanDoc и соответственно не всё там очень хорошо :)
                            +1
                            Ползуюсь VSCode + markdownlint + отдельный репозиторий на github для синхронизации. И удобно, и есть история, и habr более менее адекватно рендерит.
                              +1

                              Ещё один лайфхак. В gitlab есть встроенная web-IDE. Она умеет работать с md. Там же можно делать ревью, там же просматривать, там же редактировать, там же история правки в понятном любому разработчику виде. При этом ещё и редактировать можно в любимом редакторе. Там же можно временно хранить картинки. Ветки git, наверное, никому в такой задаче не приводятся, но они есть.

                                +2

                                С маркдауном у Хабра проблема в том, что он не склеивает строки. Поэтому приходится проходиться по статье, написанной в маркдаун ещё одним конвертером, который конвертит маркдаун в хабровский маркдаун.

                                  0

                                  Это каким? Специально для этой цели разработал MarkConv. Помимо склеивания, он конвертит спойлеры, адреса картинок с локальных на habrastorage, относительные ссылки (удобно для содержания) и делает другие полезные вещи.

                                    0

                                    Когда-то давно я сделал свой форк pandoc и добавил туда хабросовместимый html. Потом на хабре появился маркдаун и я стал склеивать строки вместо хабра каким-то ключиком в pandoc. Последние статьи у меня написаны в org-mode.


                                    Но есть один нюанс — если ты работаешь над статьёй не один, а есть какой-то редактор или кто-то в этом духе, то никакого маркдауна и тем более оргмода нельзя. Надо выкладывать у гуглдоки, чтобы там все делали правки.

                                      0
                                      Но есть один нюанс — если ты работаешь над статьёй не один, а есть какой-то редактор или кто-то в этом духе, то никакого маркдауна и тем более оргмода нельзя.

                                      Можно конечно, для чего Git с GitHub существуют? Я бы даже сказал нужно. Одно из достоинств Markdown — простые дифы. К тому же разрывы строк как раз и существуют, чтобы вместо одной огромной измененной строки размером в абзац отображалась строка размером 80-120 символов.

                                        0

                                        Всё вы правильно говорите, только редакторы не знают что такое Git и работать с ним, конечно, не умеют. Редакторы исправляют косноязычность, ошибки всякие и так дале, с их точки зрения инструмент для совместной работы над текстом это именно гуглдок. Да и, к сожалению, не только с их точки зрения, а с точки зрения вообще всех, кто не программист в широком смысле этого слова.

                                  +2
                                  Я начинал делать IDE для написания текстов на Хабр, но из-за нагрузки прекратил, и сейчас оно существует в виде набора полезных скриптов (которые очень заточены на мой ноутбук, и для отчуждения и превращения в удобный софт нужна значительная работа). В комментариях к этому комменту можно пожелать, какие фичи вы бы хотели видеть в такой IDE.
                                    0
                                    Прям IDE? o_O
                                    Достаточно было бы WISIWIG, который отображает именно так, как отобразит хабр.
                                      +1

                                      Бывали периоды, когда выпускал по одной хабростатье в день. А может и по нескольку, если считать помощь в вычитке другим авторам. Когда дрожащими руками делаешь перевод статьи на тридцать страниц, пытаясь успеть к концу дня, параллельно координируясь с автором, дизайнером, корректором и остальными — возникают совершенно специфические требования к удобству. Или например, если тебе нужно сделать статью по докладу, в котором 200 слайдов, которых у нас в блоге JUG.ru Group предостаточно. Это как хороший автомобиль, один раз в день в булочную можно съездить и на Оке, а вот целыми днями жить в Оке крайне не рекомендуется :-) В общем, это сложно объяснить словами, и это надо показывать пачку скриптов, написанных за последний год. Возможно, однажды я соберу их во что-то, что смогут использовать другие люди.

                                    0
                                    Хм. А как бы из уже сверстанного HTML перегнать в Markdown?
                                      0
                                      По запросу «convert html to markdown» нашлось несколько конвертеров, но все они не прошли быстрый тест и посыпались на тексте с несколькими тегами <code/>. Дальше копать не стал.

                                      Предполагаю, что быстрее всего переразметить готовый HTML руками, но был бы рад ошибаться.
                                        0

                                        Я юзаю эти кривые реверсеры, и потом допиливаю руками. Не видел ещё ни одного реверсера, который работал бы хоть сколько-то осмысленно хорошо. В последний раз юзал Reverse Markdown, в принципе жить можно.

                                          0

                                          Pandoc тоже не смог?

                                        0
                                        del
                                          0

                                          Я пишу статью на гитхабе в собственном репозитории Articles причем в GitHub формате Markdown (да, да, он существенно отличается от хабровского). С помощью своей утилиты MarkConv перегоняю их в формат хабра. Как уже писал ранее, он склеивает строки, конвертит спойлеры, меняет адреса картинок с локальных на habrastorage, преобразует относительные ссылки (удобно для содержания) и делает другие полезные вещи.


                                          В связи с тем, что не так давно приватные репозитории стали бесплатными, можно создать приватный репозиторий для черновиков и паблик — для финальных опубликованных топиков. Пушить и туда и туда очень просто, т.к. это Git. Как следствие, получаем механизмы Issues, Pull Request, историю изменений, возможность бекапа локально или на другие сервисы.


                                          Кстати, тоже планирую написать статью о том как писать статьи, но используя Git и GitHub (GitLab) и внешние IDE. Правда надо доделать до конца что запланировал.

                                            0

                                            А использовать Google Docs для Markdown… Ну, если честно, не очень.

                                              0

                                              Писать в гугл-доке маркдаун неудобно, конечно. Поэтому пишется как обычно, заголовки размечаются встроенными стилями, а потом, когда все правки от всех заинтересованных внесены, документ конвертируется в маркдаун.

                                              0
                                              Ёпрст, научите меня уже делать всплывающие подсказки на хабре (слово подчеркнуто пунктиром, при наведении мышой всплывает разъяснение) — а то перечитал стопицот документаций, а найти всё не могу и не могу!
                                                0

                                                Древние подсказывают, что это делается через ABBR.


                                                abbr title="тэг Abbr">ABBR</abbr
                                                
                                                
                                                  0

                                                  О величайший и мудрейший, а в какой священной книге это написано сам-то как узнал? :)

                                                  0

                                                  Что-то на мобиле оно никак не смотрится… Или я просто не умею интуитивный интерфейс?

                                                    0
                                                    Рассчитано, вроде, на наведение мышкой.
                                                      +2
                                                      Да, я заметил. Поэтому хотел бы обратить внимание хаброавторов на заложенную в этот прекрасный тэг дискриминацию по признаку наличия мышки. Просто не используйте его для того, чтобы спрятать что-то важное.
                                                0
                                                Весьма не плох https://paper.dropbox.com умеет в Markdown
                                                  0
                                                  Кстати, да. Забыл его упомянуть в посте, неплохая альтернатива gdocs.
                                                  –2
                                                  Для того чтобы напИсать «идиот» следует вставить двойные апострофы (тогда они не отображаются) затем тире-пробле-тире (тоже не видно) затем альт+255+альт+255 и букву " И" (пробел — обязательно).
                                                  Примерно — так.
                                                  0
                                                  1. Разбивайте текст на абзацы
                                                  ..., но при этом не превращайте статью в распечатку чата, начиная каждое предложение с новой строки.
                                                    0

                                                    На iPhone, iPad и MacBook использую Bear. Поддерживает и MD и HTML. Экспортирует так же в MD, HTML, TXT, DOCX, PDF и прочее. Моментально синхронизируется, что очень удобно, так как часто переключаюсь между девайсами.
                                                    Для предосмотра просто копирую в хабраэдитор.

                                                      0
                                                      А MD в HTML умеет экспортировать?
                                                        0
                                                        Да, хоть в JPG.

                                                        Полный список:
                                                        TXT, MD, PDF, HTML, RTF, DOCX, JPG.
                                                      0
                                                      del.

                                                      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                                                      Самое читаемое