Статьи — это тоже исходный код {

    Title


    Открываю VS Code и начинаю набирать статью с самого начала. Но вот незадача — формат маркдауна не совсем совместим с имеющимся форматом Хабра. Получается выхода нет и придётся возвращаться к встроенному редактору Хабра;


    Или не придется?

    В голову пришла идея написать утилиту, которая конвертирует разные форматы маркдаунов друг в друга, например, из формата GitHub в формат Habr;


    Такую программу я в итоге и разработал. Теперь не надо копировать статьи в редактор Хабра, чтобы посмотреть как она выглядит, можно продолжать писать в любимом VS Code;


    Хотя я и использую множество плагинов VS Code, но мысли о неэффективном процессе написания статей не исчезли. Раз уж я набираю текст в VS Code, то почему бы сразу не делать коммиты контента в гит-репозиторий?


    Это дало бы немало новых возможностей, которыми пользуются программисты: версионирование, бекапы на локальные носители или веб-сервисы, правки от редакторов и пользователей. А еще можно внедрить CD/CI;


    В итоге, я написал небольшой гайд для разработчиков, как писать техническую документацию в редакторах, используя мою утилиту. Саму утилиту можно посмотреть в моём репозитории на GitHub;





    Пишем {



    Написание статьи начинается с выбора текстового редактора. Существует большое количество специальных текстовых редакторов и всех их рассмотреть очень трудно, поэтому я остановился на наиболее популярных и разнородных;


    Visual Studio Code


    Возможности по написанию статей внушительны, тут и поддержка Markdown и разнообразие плагинов под любую задачу. Также есть подсветка синтаксиса кода;


    Интерфейс VS Code удобно разделён на окна: слева отображается код текста, а справа — визуализация кода, работающая в реальном времени;


    О VS Code написано много статей и гайдов, в том числе и на Хабре, поэтому не буду много расписывать о возможностях редактора, а перечислю плагины, которые оказались очень полезными для меня:


    • Проверка синтаксиса
    • Проверка форматирования
    • Форматирование таблиц
    • Генерация оглавления

    Проверка синтаксиса


    Проверка синтаксиса позволяет снизить количество ошибок по невнимательности, экономит силы редакторов, а также уменьшает количество негатива от читателей;


    В VS Code, для проверки синтаксиса, я использую Code Spell Checker (русский словарь необходимо устанавливать отдельно), и Grammarly;


    Проверка форматирования


    В данной статье текст — это исходный код, а значит к нему применимы принципы форматирования. Расширение markdownlint проверяет код на соответствие стандартным правилам, с которыми можно ознакомиться на странице репозитория этого расширения;


    Форматирование таблиц


    Table Formatter


    В Markdown громоздкий и не особо удобный синтаксис для описания таблиц. К счастью, существуют различные расширения, которые позволяют улучшить процесс создания и форматирования таблиц, например, расширение Table Formatter;


    Генерация оглавления


    Markdown TOC


    Иногда возникает необходимость сгенерировать оглавление (Table of Content, TOC) для всего документа на основе заголовков, причем чтобы оглавление автоматически обновлялось. Для этого существует несколько расширений, но мне нравится плагин Markdown TOC. Данный плагин я использовал для генерации оглавления в этой статье;


    Typora


    Typora возможно понравится любителям визуального программирования, так как совмещает в себе плюсы WYSIWYG и текстовых редакторов и позволяет сразу увидеть финальное представление текста в документе. Typora поддерживает Markdown;


    Typora


    Веб-интерфейс как редактор


    Можно писать статьи сразу в веб-браузере, используя, например, Хабр, GitHub, stackedit.io, dillinger.io и другие сервисы. Хотя это не так удобно и не особо вписывается в процессы разработчика, зато дает возможность набирать текст хоть на планшете или телефоне;


    Pandoc, как универсальный конвертер


    Pandoc универсальная утилита, позволяющая конвертировать одни текстовые файловые форматы в другие. Можно использовать word или latex как основной текстовый редактор и в дальнейшем, с помощью pandoc, конвертить один формат в другой. Pandoc поддерживает огромное количество форматов, например, md, docx, txt, rtf, pdf, html и другие. При этом, pandoc очень прост в использовании и позволяет форматировать один файл в другой с помощью одной команды, например:


    pandoc text.docx -o text.md

    Также есть веб-версия, позволяющая воспользоваться возможностью конвертации в режиме онлайн;


    }


    Конвертируем {



    После того как статья написана, её нужно сконвертировать в Markdown-формат Хабра. Этого можно было бы избежать, если бы markdown-синтаксис Хабра полностью сочетался с GitHub Flavored Markdown, который реализуется во многих других редакторах, в частности, в VS Code;


    Однако существует несколько несоответствий, самое важное из которых — неправильная обработка переносов строк. Из-за этого приходится использовать однострочные абзацы, что плохо сочетается с системами контроля версий — diff раздувается и становится малоинформативным. Есть и другие различия: спойлеры, относительные ссылки, которые часто используются в оглавлении. С полным списком можно ознакомиться на странице issues в репозитории dear-habr. MarkConv разрешает эти несоответствия;


    Используем MarkConv


    Конвертировать правильно можно с помощью утилиты MarkConv следующим образом:


    1. Устанавливаем .NET Core (если его еще нет).


    2. Устанавливаем .NET Tool следующим образом:


      dotnet tool install -g MarkConv.Cli --version 1.0.0 --add-source https://www.myget.org/F/mark-conv/api/v3/index.json

    3. Конвертируем статью в формат маркдаун-синтаксиса Хабра следующим образом:


      markconv -f <article.md> -o Habr


    Утилиту можно запускать и в batch-режиме из папки с md-файлами, что позволит запустить конвертацию сразу нескольких файлов одновременно;


    По завершению процесса конвертирования статью можно публиковать на Хабр;


    Стоит отметить, что MarkConv конвертирует не только в формат Хабра, но и в формат dev.to, а также делает другие полезные проверки и замены;


    Проверка синтаксиса с помощью MarkConv


    В тексте в формате Markdown нет формальных ошибок — уместна любая последовательность символов. Это и достоинство и недостаток — текст всегда можно прочитать, но какие-то вещи могут ненамеренно отображаться некорректно;


    Однако в таком тексте могут использоваться HTML-секции, в которых могут быть ошибки типа незакрытых тегов. В своих статьях я сразу нашел несколько, например:


    [INFO] Converting of file /home/appveyor/projects/articles/Modern-Presentations-Format/Russian.md...
    [WARN] Incorrect nesting: element </href> at [358,162..166) closes <a> at [358,14..15)

    Ограничение на размер текста относительно тега cut


    На Хабре есть резонные ограничения на размер текста до и после использования тега cut. MarkConv проверяет эти правила и выводит ошибку при нарушении, например:


    You need to insert <cut/> tag if the text contains more than 1000 characters

    Проверка абсолютных ссылок


    Использование ключа --checklinks позволит запустить утилиту MarkConv на проверку всех ссылкок вида http://;


    На данный момент это работает с некоторой задержкой и не всегда корректно, возможно таким образом на внешних сервисах реализована защита от DDoS-атак;


    Замена отображения локальных адресов ресурсов на абсолютные


    Чтобы ресурсы не зависели от внешних сервисов (например, картинки), то имеет смысл использовать тег linkmap следующим образом:


    <linkmap src=Markdown.svg dst=https://habrastorage.org/getpro/habr/post_images/a40/f88/64c/a40f8864c5f8db7888076cf30f5411f5.svg />

    где: src — адрес локального ресурса, а dst — удалённого.


    При этом картинку нужно еще дублировать на сторонний сервис. Таким образом, статья всегда будет правильно открываться локально, даже если сервер с картинками упал, в том числе и Habrastorage;


    Посмотреть как это работает можно на примере одной из моих статей;


    Этот метод также можно использовать для редиректа ссылок на локальные статьи — одна статья будет всегда ссылаться на другую;


    Кликабельная титульная картинка


    Часто заглавную картинку делают кликабельной, чтобы при клике открывалась сама статья. Для этого достаточно добавить такую строчку в исходник текста:


    <linkmap src=HeaderImageLink dst=https://habr.com/путь-к-статье />

    }


    Храним {



    Исходники текста написаны, а публикуемые файлы получены с помощью конвертера. Теперь хотелось бы их сохранить в репозитории, но сначала необходимо определиться с структурой репозитория. Я разработал такую структуру:


    • Каждая статья хранится в определенной папке. Название этой папки — перевод заголовка статьи, в котором пробелы заменены на дефисы, а запрещенные в url-символы игнорируются, например, для этой статьи названием будет являться следующее имя: Article-is-also-code;
    • Сам md файл внутри этой папки именуется языком, на котором эта статья написана, например, Russian.md или English.md;
    • Опционально. Локальные картинки и ресурсы хранятся либо в корневой папке статьи, либо в подпапке Images и маппятся с помощью утилиты MarkConv;

    Использование такой структуры позволяет понять о чем статья и на каком языке она написана. Например, для этой статьи ссылка такая: https://gitlab.ptsecurity.com/writers/Articles/blob/master/Article-is-also-code/Russian.md;


    В качестве навигации по документам, расположенным в репозитории, можно использовать файл README.md в корне репозитория, который содержит в себе список статей в хронологическом порядке, даты и порталы публикаций, описания и другую информацию;


    Также имеет смысл хранить статью в приватном репозиторий до её публикации. А после публикации пушить ветку в зеркальный публичный репозиторий. В GitHub и GitLab такая возможность предоставляется бесплатно;


    }


    Вычитываем {



    После того, как исходники статьи написаны и запушены, редакторы могут сделать "ревью" статьи, т.е. вычитку. Можно использовать знакомые для программиста инструменты: создавать issue, предлагать pull request и даже принимать участие в дискуссиях — новой возможности GitHub;


    После публикации статьи предлагать изменения сможет не только ограниченный круг лиц, но и все зарегистрированные пользователи. Так можно удобно исправлять имеющиеся опечатки;


    }


    Автоматизируем {



    Непрерывная интеграция — вишенка на торте любого более менее зрелого процесса разработки. Благодаря ей, сторонние сервисы после каждого коммита проверяют, конвертируют и архивируют статьи, а затем выкладывают их в собственное хранилище;


    Готовый результат можно сразу копировать в черновик Хабра, минуя запуск утилиты на локальном компьютере. Таким образом, становится возможным править статьи с помощью веб-браузера;


    Я использую сервисы GitHub Actions и AppVeyor;


    GitHub Actions


    GitHub Actions удобно использовать когда вся разработка ведется на GitHub, к тому же он работает на приватных репозиториях даже в базовом бесплатном варианте;


    В репозитории со статьями достаточно создать файл по аналогии с данным примером:


    publish-articles.yml
    name: Articles Converting and Publishing
    
    on: [push, pull_request]
    
    jobs:
      build:
        # Можно использовать и windows
        runs-on: ubuntu-latest
    
        steps:
          # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
          - uses: actions/checkout@v2
    
          # Установка .NET Core
          - name: Install .NET Core
            uses: actions/setup-dotnet@v1
            with:
              dotnet-version: 3.1.101
    
          # Установка .NET Core Tool
          - name: Install MarkConv
            run: dotnet tool install -g MarkConv.Cli --version 1.2.0 --add-source https://www.myget.org/F/mark-conv/api/v3/index.json
    
          # Запуск утилиты MarkConv на все статьях в корневой папке
          - name: Run MarkConv
            run: markconv -f ./ -o Habr --checklinks
    
          # Публикация сконвертированных статей
          - name: Deploy Articles
            uses: actions/upload-artifact@v2
            with:
              name: articles
              path: ./_Output

    AppVeyor


    Данный сервис для меня даже оказался удобней, поскольку он может публиковать статьи по файлам, а не единым архивом. Конфигурация сервиса находится в файле appveyor.yml;


    appveyor.yml
    image:
    - Ubuntu
    version: "{build}"
    skip_branch_with_pr: true
    
    before_build:
    - ps: |
        dotnet tool install -g MarkConv.Cli --version 1.2.0 --add-source https://www.myget.org/F/mark-conv/api/v3/index.json
    build_script:
    - ps: |
        markconv -f ./ -o Habr --checklinks
    after_test:
    - ps: |
        cd ./_Output
        foreach ($file in Get-ChildItem ./)
        {
            Push-AppveyorArtifact $file.Name
        }

    }


    Публикуем {



    Артефакты получены, теперь можно копировать их на Хабр и публиковать. К сожалению, этот шаг пока что невозможно автоматизировать, потому что "API Хабра закрыт на реконструкцию";


    Надеюсь, в будущем публичный доступ восстановится, и процесс публикации статей станет более автоматизированным;


    }


    Заключение {


    Итак, я пишу статьи в VS Code, храню их в Git, использую GitHub для разработки и автоматизирую с помощью GitHub Actions — неплохой набор для программиста;


    Я нашел для себя описанные наработки удобными для технических статей, но пока что слишком громоздким для одноразовых статей типа новостных. Мне нравится воспринимать статьи не просто как статический текст, который пишется один раз, а средство коммуникации, которое включает в себя меняющийся со временем контент и фидбек от других пользователей. Первого можно достичь, если представлять текст статьи в виде кода, второе предоставляет Хабр и другие социальные сервисы. Кроме того, собственный репозиторий со статьями — надежный способ бекапа, т.к. хранить его можно как на локальном диске, так и на GitHub;


    Чтобы понять, удобны ли данные наработки для вас, я подготовил несколько опросов, после которых станет понятней, стоит ли дальше развивать эту концепцию;


    В следующей статье я хотел бы рассказать о том, как разрабатывалась утилита для конвертации MarkConv, о ее технических деталях и возможном развитии;


    }

    Only registered users can participate in poll. Log in, please.

    Какой редактор используете?

    • 8.0%Хабровский текстовый9
    • 6.2%Хабровский WYSIWYG7
    • 50.0%VSCode, либо другой текстовый блокнот56
    • 11.6%Typora, либо другой визуальный Markdown редактор13
    • 8.0%Google Docs, либо другой облачный сервис9
    • 16.1%Microsoft Word, либо другой оффлайн редактор18

    Где храните статьи?

    • 17.6%Черновики на хабре18
    • 26.5%Документы Google Docs, либо другой облачный сервис27
    • 54.9%Локально на диске56
    • 36.3%В Git репозитории37

    Какой формат используете?

    • 8.8%Хабровский WYSIWYG10
    • 11.5%HTML13
    • 61.1%Markdown69
    • 11.5%Другой WYSIWYG (Word, Google Docs)13
    • 7.1%Другой текстовый (ReStructuredText, AsciiDoc, Latex)8

    Что думайте о таком процессе разработки статей?

    • 30.8%Устраивает существующая функциональность24
    • 41.0%Попробовал бы, если было бы проще для пользователя (слишком много мороки).32
    • 14.1%Попробую использовать для технических статей, но не для новостных11
    • 14.1%Давно не хватало — буду пробовать использовать11

    Интересно ли узнать о деталях разработки конвертера MarkConv?

    • 61.6%Да53
    • 38.4%Нет33

    Similar posts

    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 46

      +6
      1. Пишем в Google Docs
      2. Ctrl-C > Ctrl-V в новый редактор хабра
      3. Исправить места с поехавшим форматированием
      4. Поматериться на общую кривокосость нового редактора
      5. Отправить пачку новых косяков и утешить себя тем, что доделают же его когда-то
      6. Опубликовать

      Когда из этого алгоритма уйдут пункты 4 и 5, жить станет намного приятней, чем держать пачку конвертеров и проверяльщиков наконверченного.
        +4

        У меня процесс выглядит так:


        1. использую github pages для своего сайта со статейками
        2. к себе на сайт пишу черновик RU/ENG(вобще это обычно расшировки выступлений своих)
        3. расскидываю ссылки заинтересованным, правлю.
        4. копирую на хабр как есть. приходится подправлять url картинок и хабракат добавлять

        такую схему уже года 3 использую

        • UFO just landed and posted this here
            +1

            Тоже недавно задумался над тем, как улучшить написание в маркдауне :) Остановился на VsCode и плагинах к нему. Из неупомянутых выбрал:


              +4

              Скажите, а конвертирующий скрипт что делает с оглавлением? Хабр обычное markdown-оглавление не понимает, насколько помню, надо вручную ссылки делать.


              Лично я пишу в Емаксе в режиме org-mode, откуда экспортирую в Github Markdown при помощи pandoc, после чего правлю всякую ерунду небольшим макросом.

                +1

                Я генерирую оглавление с помощью плагина Markdown TOC в VSCode, об этом также писал в статье. Но есть и другие плагины.


                А MarkConv конвертирует относительные ссылки из обычного формата в формат хабра. Например, #генерация-оглавления преобразуется в #generaciya-oglavleniya. На примере этой статьи видим, что оглавление работает :) А в репозитории MarkConv есть и тесты.

                  +1

                  Ага, понял, как раз этого фокуса (конвертации ссылок) в статье и нет.


                  Может, стоит добавить пояснение? Мало ли, кто будет что-то подобное делать другими инструментами, или будет в ваше решение вникать.


                  В любом случае спасибо!

                    +1

                    Вообще немножко есть в абзаце Конвертируем:


                    Есть и другие различия: реализация спойлеров, внутренних ссылок и.т.д;

                    Но я вас понял: подумаю над тем, чтобы подробней это расписать.

                –2

                Я вообще свой Хабр сделал на гитхабе: https://github.com/nin-jin/habhub

                  +4

                  До хабра это не дотягивает. Использовать GitHub, но набирать статьи в issues — странное решение — они для этого не предназначены, т.к. отсутствует версионирование. Почему бы просто не писать статьи в формате md и хранить их в репозитории?

                    0

                    Чтобы была возможно комментирования. Но на гитхабе уже появились дискуссии. Надо будет попробовать их.

                      0

                      Ну так можно при создании поста просто создавать новую issue для комментариев.

                        0

                        Руками это делать не удобно. Да и удобней, когда комменты сразу под постом.

                +1

                Моя мечта чтобы люди перешли с Confluence на markdown и писали документацию через коммиты.

                  0

                  Проблема не в написании документации, а в правилах агрегатирования, слежения и обновления.

                    0

                    Ну некоторые люди перешли. Вам надо чтобы все перешли или какие-то определённые?

                      +2
                      А моя мечта в том, чтобы некоторые люди документацию как таковую начали писать.
                        0

                        Этому миру не хватает инструментов вроде cargo doc в других языках

                        +5
                        Спасибо за крутой пост — здорово и по делу написано, свёрстано с душой :)

                        Я все материалы пишу в GoogleDocs — на панели закладок всегда есть ссылка на новый док. Это не только даёт уверенности, что он не потеряется (в Хабре несохранённый черновик лежит в localStorage и может потеряться, а с локальным редактором/ноутбуком тоже может что-нибудь случиться), но и позволяет оперативно что-то коллективно поправить (или согласовать). Второе многим авторам Хабра не нужно, но для меня это уже часть процесса — показать коллеге, которая всегда что-то по существу добавит-поправит. Да, гугл на днях прилёг, но это скорее исключение, ни разу такого не встречал больше. Также любую статью легко найти через поиск в аккаунте.

                        Картинки вставляю прямо в гугл-документ, уже оптимизированные (обычно 1500px, несмотря на то, что в Хабре контентная часть 780). Затем всё это выделяю, копирую и вставляю в этот конвертер — он выдаёт код поста, которому нужно минимум правок.

                        А далее, важный момент: вставляю код из конвертера в черновик на Хабре и сохраняю его — в результате этого картинки автоматом заливаются на Хабрасторож. То есть и в самом документе гугла были картинки (для наглядности) вместо текстовых пометок 123.jpg, и возиться с их заливкой не нужно. Получившийся код подходит и для блога, где как раз пригождаются картинки большого размера )

                        Если вам не нужно коллективное редактирование, то новый редактор вполне комфортный для написания материала или размещения. Хотя всегда есть что доработать.
                          0

                          В gitlab достаточно удобный markdown редактор, хотя и есть отличия от хабровского формата, но не значительные, можно пометить просто перед публикацией пофиксить.
                          Поэтому можно редактировать так:


                          1. Создать репу в гитлабе (закрытую, если хотите).
                          2. Набрать статью.
                          3. Вычитать, проверить орфографию.
                          4. Дать вычитать знакомому (в отдельной ветке, он может каждое исправление как коммит делать)
                          5. Мерж.
                          6. Скопировать в хабр и пройтись по форматированию.

                          PS: набирать статью можно хоть в самом gitlab, хоть в VSCode, хоть в Intellij IDEA

                            +3
                            По-моему, нет ничего лучше, чем писать текст в Word. Как Вам наше решение в виде плагина для Word?)

                              +2

                              Word не поддерживает нормальное версионирование с помощью git, а значит коллективная работа над статьей ограничена. Кроме того, файл docx весит больше чем md, содержит больше служебных элементов, сложнее в обработке. Редактора Word нет под Linux (есть LibreOffice, но это не то).


                              Где ваш плагин можно взять поиграться?

                                +1
                                У Word есть встроенное версионирование, которое запускается диффером Git или SVN. Очень редко пользуемся.

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

                                Был период, когда можно было внести изменения в нашу работу, я смотрел на md, но так и не понял, куда деть картинки. Сейчас они запакованы в .docx. Каталог с документами выглядит удобным и понятным. Как бы вы хранили картинки, если они используются в нескольких тысячах документов?

                                Код нашего плагина закрыт, т.к. это только малая часть всей внутренней «кухни» по управлению документами в компании.
                                  +2
                                  У Word есть встроенное версионирование, которое запускается диффером Git или SVN. Очень редко пользуемся.

                                  Но какой от него толк, если на условном GitHub оно все равно не будет работать через браузер.


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

                                  У разработчиков гитхаба тоже много совместной работы с документами, тем не менее они используют Markdown и Git для документации на https://github.com/github/docs.


                                  Как бы вы хранили картинки, если они используются в нескольких тысячах документов?

                                  Как и сейчас — внутри репозитория, доступ к одной картинке может быть из нескольких документов. Как и в данной статье — ее можно открыть оффлайн. При конвертации используется информация из тегов linkmap — об этом написано в статье. В теории загрузку картинок на внешний сервис тоже можно автоматизировать, но не всегда есть доступ к API сервиса с изображениями. Но можно и сразу использовать картинки с внешнего сервиса без возни с мэппингом.


                                  Код нашего плагина закрыт, т.к. это только малая часть всей внутренней «кухни» по управлению документами в компании.

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

                                    0
                                    Я предложил практичную идею в контексте статьи, а не готовое решение. На самом деле многие компании делают именно плагины для Word, т.к. это достаточно просто. Может кто-нибудь ещё подсмотрит. Я бы не стал называть пользователей GitHub массовым пользователем документов в целом. Всё-таки, большинству не IT пользователей комбинация VS Code + MD + Git + Image Dir будет слишком сложной.
                                    0

                                    А как вообще в md решают вопрос с картинками? Скажем, если тексты редактируются оффлайн, но выкладываются на Хабр/Dropbox Paper/еще что-нибудь (и наоборот), то картинки все равно придется подтягивать вручную по одной?

                                      0
                                      Ну это вопрос скорее к KvanTTT.

                                      Я считаю это не удобным при локальном хранении и редактировании. А в случае сайта/форума с редактором md меня, например, не беспокоит, где хранятся картинки и как они версионируются.
                                        +2

                                        Если нет требования к автономности, то картинки можно хранить на том же habrastorage. Если есть — то вместе со статьей и мэппить их на картинки с внешнего сервиса при публикации.

                                  +3

                                  Пишу личные заметки, статьи, веду базу знаний именно по приведённой схеме — md + git, очень удобно.


                                  Проблем у меня две.


                                  Одна — с картинками, очень хочется такого, как в современных cms-системах когда достаточно бросить картинку из файла или просто из буфера обмена в браузер и тебе её автоматом на лету вставят-сохранят как надо, я бы очень приветствовал если бы такое в vscode появилось.


                                  Вторая — с diff'ом таблиц. Ну, такое. Вероятно, надо просто перестать рассматривать эти diff'ы и не париться, это думаю чистейшей воды профдеформация: есть люди, которые вставляют текст из ворда в cms'ку и не парятся насколько ужасная под капотом разметка (кто видел вордовские стили — тот поймёт), а есть те, кто при этом руками выправляет теги. И вот деформация в том, что я отношусь скорее к людям второго типа, поэтому по-возможности полусознательно избегаю вставки таблиц ибо геморрой.

                                    0
                                    Одна — с картинками, очень хочется такого, как в современных cms-системах когда достаточно бросить картинку из файла или просто из буфера обмена в браузер и тебе её автоматом на лету вставят-сохранят как надо, я бы очень приветствовал если бы такое в vscode появилось.

                                    Сейчас попробовал расширение Paste Image — вставлять картинки из буфера оно умеет. Но есть и другие расширения.


                                    Вторая — с diff'ом таблиц. Ну, такое.

                                    А вы пробовали описывать таблицы с помощью html тегов? Это поддерживаются и в VSCode и на Хабре.


                                    <table>
                                      <tr>
                                        <td>column 1</td>
                                        <td>column 2</td>
                                      </tr>
                                    </table>

                                    Возможно их диф будет больше радовать ваши глаза.

                                    0

                                    А кто корректирует и редактирует? Судя по требованию создавать issue и пулл реквесты — другие программисты. Но когда этим занимаются не программисты, а редакторы — объяснить им, что надо делать пул реквесты решительно невозможно. Даже предложение редактироват не ворд, а непонятно что с их точки зрения выглядит идиотским.


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

                                      0

                                      Есть редакторы, которые понимают и принимают Markdown и Git. В чатах https://t.me/technicalwriters и https://t.me/docsascode таких немало (за что им спасибо, что вызвались помочь с вычиткой).

                                        0
                                        Есть редакторы, которые понимают и принимают Markdown и Git.

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

                                          0

                                          Ну и обычных программистов для правок никто не отменял — они то разбираются в гите, как рыбы плавают в воде)

                                      0

                                      В VSCode или Atom есть прекрасные плагины для работы со стандартным markdown. Стандартный markdown принимается очень много где — на GitHub, в каждой второй системе генерации документации, в каждой IDE / текстовом редакторе.


                                      Поэтому возникает вопрос — ради написания статей и документации, зачем множить сущности? Уже скорее уж хабру надо подстроиться под общепринятые стандарты. А поправить пару косяков (даже и в новом редакторе) — не проблема.


                                      Конечно если нет цели писать статьи по КД или заниматься virtue signalling-ом.

                                        +1

                                        Это надо у разработчиков хабра спрашивать, зачем они собственный Markdown изобрели. Благодаря конвертеру, вы как раз и сможете работать со стандартным gfm.


                                        Что касается дополнительных тегов include, linkmap — их использовать не обязательно. Первый — когда требуется включить контент из другого файла, второй — если нужно отобразить локальные ресурсы на удаленные (в основном картинки). При рендере стандартного Markdown такие теги просто игнорируются (как и хабровский cut).

                                        +1

                                        У вас фигурные скобки не сбалансированы.

                                          +2

                                          Так и знал, что кто-то это подметит. Если рассматривать комментарии как дополнительный контент к статье, то она еще не закончилась, а значит скобки закрывать рано :)

                                          +1

                                          Интересно, а почему вы просто не добавили в pandoc ещё один формат?

                                            0

                                            Хороший вопрос.


                                            1. Вряд ли такое изменение примут непосредственно в проект — все-таки хабр не очень популярный. Во всяком случае мою issue в 2017 по поводу формата CodeProject отклонили:


                                              Too special-purpose. I recommend simply postprocessing the HTML, a perl one-liner will suffice.

                                            2. Я не знаю Haskell;


                                            3. Но есть и другой вариант интеграции — использовать pandoc фильтры, но:


                                              1. pandoc не дампит точную позицию AST в исходнике, а это критично, поскольку важно понимать позицию ошибки, чтобы можно было ее исправить. Хотя в следующей версии такая фича вроде должна появиться: https://github.com/jgm/pandoc/issues/4565;
                                              2. Не учитываются HTML элементы, т.е. для HTML кода просто создаются RawBlock, в моем же конвертере для корректно обработки тегов используется HTML парсер. Впрочем, это касается и используемого в текущий момент Markdown парсера;
                                              3. На момент старта я не знал о фильтрах;
                                              4. pandoc — дополнительная зависимость.


                                            Но вообще есть идея попробовать заюзать pandoc со следующей версии, чтобы поддерживать намного больше языков, а не только Markdown.

                                              +1

                                              Когда у меня возикла проблема с хабровским маркдауном я сделал форк pandoc, скопипастил модуль для маркдауна и сделал нужныне мне изменения. Хаскел я тоже не знаю, но всё оказалось не так уж сложно.


                                              Я правда не обновлял свой форк уже лет 5, но мне хватает. Если интересно немного подробностей, например, что знание Хаскела не так уж и нужно, можно посмотреть вот этот коммит https://github.com/poxu/pandoc/commit/b6dc432cb3c128be67692d53b41cb3aebc0340bf

                                                0

                                                Насколько я понял, в вашем форке добавлена только склейка строк, но этого и так можно добиться с помощью опции --wrap=none. Для корректной конвертации относительных ссылок и спойлеров нужно побольше кода.

                                                  0
                                                  Насколько я понял, в вашем форке добавлена только склейка строк, но этого и так можно добиться с помощью опции --wrap=none.

                                                  Огромное спасибо за подсказку. То ли не было этой опции в pandoc тогда, то ли я не нашёл.


                                                  Для корректной конвертации относительных ссылок и спойлеров нужно побольше кода.

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


                                                  Ваш пример впечатляет и вдохновляет. Я пишу статьи в org-mode и потом конвертером преобразую к нужному формату. Создаётся впечатление, что ваша разработка сделана как раз для таких как я.

                                                    0
                                                    Я пишу статьи в org-mode и потом конвертером преобразую к нужному формату. Создаётся впечатление, что ваша разработка сделана как раз для таких как я.

                                                    Пробуйте на здоровье — баги можно репоритить в репозиторий или даже предлагать пулл-риквесты. Я старался реализовать как можно более простое взаимодействие с конвертером, и сейчас требуется только один обязательный параметр, имя input файла, все остальные "настройки" описываются в самой статье, а не через параметры командной строки (как было раньше).

                                          Only users with full accounts can post comments. Log in, please.