Не найдено

markdownForever

author:

• Sof <hellosof@gmail.com> autonumber-headings: 1 css:
• style.css date: Friday, July 17, 2020 extratags: 1 extratags-back: 0 filename: doc_en include-after:
• '%addonDir%/doc/dependencies.md' keywords: documentation, MarkdownForever, NVDA add-on, english lang: ru langd: ru subtitle: Полнофункциональный конвертер Markdown и HTML для NVDA template: default title: Документация MarkdownForever %addonVersion% toc: 1 ...

Содержание %toc%

Введение

MarkdownForever — это небольшое дополнение для NVDA, которое позволяет легко конвертировать содержимое Markdown или HTML. Просто напишите или отобразите любой текст в формате Markdown или HTML и нажмите простую комбинацию клавиш, чтобы мгновенно преобразовать или предварительно просмотреть результат в любое время, точно так, как он будет выглядеть на вашей итоговой веб-странице, или в виде исходного кода HTML, готового для вставки в любое текстовое поле, поддерживающее HTML.

MarkdownForever умеет:

• Преобразовывать Markdown в HTML
• Преобразовывать Markdown в исходный код HTML
• Преобразовывать HTML в Markdown
• Преобразовывать Markdown в форматированный HTML

Но что же это за таинственный зверь такой — Markdown?

Согласно Википедии,

Markdown — это облегчённый язык разметки с синтаксисом форматирования обычного текста. Его дизайн позволяет преобразовывать его во многие выходные форматы, однако оригинальный инструмент с тем же именем поддерживает только HTML. Markdown часто используется для форматирования файлов readme, для написания сообщений в интернет-форумах и для создания форматированного текста с помощью текстового редактора.

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

Итак, вместо того чтобы писать веб-документы на HTML с риском допустить ошибку, вы будете использовать легко запоминающиеся теги, и ваша работа будет выполнена в кратчайшие сроки. С помощью Markdown вы сможете делать примерно то же, что и с HTML: заголовки, упорядоченные (нумерованные) или неупорядоченные (маркированные) списки, ссылки и даже таблицы.

Например, если вы хотите сделать заголовок первого уровня, вы напишете один символ решётки (#), за которым следует название вашего заголовка, с пробелом между ними или без:

#Это пример заголовка первого уровня

который в итоговом HTML-документе будет выглядеть так:

Это пример заголовка первого уровня

Для заголовка второго уровня вы используете два символа решётки, для третьего — три и так далее.

Теперь давайте создадим маркированный список элементов. Для этого вы можете поставить перед каждым элементом списка звёздочку (*). Вот пример:

• Апельсины.
• Сахар.
• Молоко.

что будет выглядеть так:

• Апельсины
• Сахар
• Молоко

Вы также можете создать ссылку, заключив название ссылки в квадратные скобки ([]), а затем сразу без пробелов указав URL в круглых скобках. Например:

[Нажмите здесь, чтобы посетить сайт NVAccess](https://www.nvaccess.org)

что даст вам:

Нажмите здесь, чтобы посетить сайт NVAccess

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

Преобразование Markdown в HTML

Эта функция позволяет преобразовать любой отображаемый на экране текст Markdown в HTML, показывая, как ваша разметка Markdown будет выглядеть в итоговом HTML-документе. Это может быть документ, который вы написали в формате Markdown, файл .md, который уже есть на вашем жёстком диске, или текст Markdown, найденный на веб-странице. По умолчанию MarkdownForever преобразует весь отображаемый в данный момент текст, но вы также можете выделить только определённую часть для преобразования.

Вы можете использовать следующие команды:

• NVDA+ALT+b: Результат отображается как веб-страница в вашем браузере по умолчанию.
• NVDA+ALT+n: Результат отображается как веб-страница в виртуальном буфере NVDA.

Обратите внимание, что рекомендуется использовать отображение в браузере вместо виртуального буфера NVDA. Некоторые теги, особенно теги HTML5, такие как <details>, не поддерживаются средством рендеринга виртуального буфера.

Преобразование Markdown в исходный код HTML

Это преобразует текст Markdown в чистый язык HTML. После этого вы сможете скопировать и вставить его в HTML-файл, в сообщение на форуме или в любое текстовое поле в интернете, где поддерживается код HTML.

Доступны следующие команды:

• NVDA+ALT+l: Результат отображается в виртуальном буфере NVDA.
• NVDA+Ctrl+h: Копирует исходный код HTML в буфер обмена.

Преобразование HTML в Markdown

Эта функция пытается создать текст Markdown из содержимого исходного HTML-кода. Как обычно, это работает для всего текста, отображаемого на экране, или для специально выделенной части. Доступны следующие команды:

• NVDA+Alt+k: Отображает результат в виртуальном буфере NVDA.
• NVDA+Shift+g: Копирует результат в буфер обмена.

Вы также можете преобразовать HTML-веб-страницу в Markdown, просто выделив её URL. Однако вы должны сначала убедиться, что движок преобразования HTML2Text правильно установлен в качестве движка по умолчанию в настройках MarkdownForever, которые находятся в подменю «Параметры» NVDA.

Преобразование Markdown в форматированный HTML

Эта функция преобразует ваше содержимое Markdown в форматированный HTML и копирует его в буфер обмена. Форматированный HTML будет выглядеть как любая веб-страница, отображаемая вашим браузером, с кликабельными ссылками, заголовками и т.д. Он может быть сгенерирован только из содержимого Markdown. Он не работает с исходным кодом HTML. Чтобы выполнить это действие, нажмите NVDA+Shift+h.

Обратите внимание, что форматированный HTML можно вставлять в такие приложения, как Microsoft Word, Wordpad, Thunderbird, некоторые поля с форматированным текстом на веб-страницах и т.д. Однако его нельзя вставить в текстовый редактор, такой как Блокнот, Notepad++ и т.п.

Интерактивный режим

Интерактивный режим — это функция, которая представляет все возможности MarkdownForever в удобном диалоговом окне, предлагая ещё больше полезных дополнительных возможностей. Чтобы открыть интерактивный режим, нажмите NVDA+CTRL+i. Вот описание экрана в порядке перехода по табуляции:

• «Преобразовать в»: Этот первый комбинированный список позволяет выбрать направление преобразования: HTML, исходный код HTML или Markdown. Используйте клавиши со стрелками вверх и вниз для выбора.
• «Создать оглавление»: Этот флажок позволит вам создавать или не создавать индекс глав вашего итогового HTML-документа с кликабельными ссылками, ведущими к каждой главе. Состояние этой опции также может быть установлено по умолчанию в настройках MarkdownForever.
• «Пытаться автоматически нумеровать заголовки»: Если отмечено, Markdown Forever попытается добавить к вашим заголовкам (или главам) числовые префиксы в соответствии с уровнем каждого заголовка, например «1.» для заголовка уровня 1, «1.1.» для заголовка уровня 2 и т.д.
• «Включить расширенные теги»: Если этот флажок установлен, он включает возможность использования специальных тегов в вашем содержимом Markdown для автоматической вставки таких вещей, как текущая дата или время. Состояние этой опции также может быть установлено по умолчанию в настройках MarkdownForever.
• «Разрешить обратное преобразование расширенных тегов»: Этот параметр определяет, должны ли расширенные теги быть преобразованы обратно в их исходную форму (например %date%) при преобразовании HTML-содержимого, сгенерированного Markdown Forever, обратно в Markdown.
• «Заголовок»: Здесь вы можете ввести заголовок вашего HTML-документа, который будет виден в интернет-браузере.
• «Соответствующий блок метаданных»: Это поле только для чтения отображает сгенерированный блок метаданных.
• «Создать соответствующие метаданные из исходного кода HTML»: При преобразовании исходного файла HTML в Markdown предпринимается попытка определить метаданные из исходного кода (заголовок, язык, имя файла и т.д.) и создать для вас блок метаданных. Эта опция доступна только для преобразования HTML в Markdown.
• «Показать в виртуальном буфере»: Эта кнопка откроет ваше преобразованное содержимое в виртуальном буфере NVDA.
• «Показать в браузере»: Это отобразит ваше преобразованное содержимое в вашем интернет-браузере по умолчанию.
• «Копировать в буфер обмена»: Это поместит ваше преобразованное содержимое в буфер обмена Windows, готовое к вставке.
• «Сохранить как»: Это предложит вам сохранить преобразованный документ на жёстком диске через стандартное диалоговое окно «Сохранить как». Место сохранения по умолчанию также может быть установлено в настройках MarkdownForever.

Необязательный блок метаданных

Блок метаданных позволяет установить определённые параметры для конкретного документа, независимо от настроек по умолчанию. Он должен находиться в самом начале документа и начинаться с трёх дефисов («---») и заканчиваться тремя точками («...») или тремя дефисами («---»). Каждая запись должна быть введена в следующей форме: ключ: «значение» (значение должно быть заключено в кавычки). После блока метаданных должна быть пустая строка.

Список поддерживаемых метаданных

• author (или authors): Указывает одно или несколько имён авторов документа (см. пример ниже). Это будет добавлено в заголовок HTML-файла. Этот ключ не чувствителен к регистру.
• autonumber-headings: Указывает, следует ли автоматически нумеровать заголовки. Возможные значения: true (1) или false (0).
• css (или CSS): Указывает один или несколько файлов CSS для оформления вашего документа (см. пример ниже). Этот ключ не чувствителен к регистру.
• date: Указывает дату для вашего документа. Это будет добавлено в заголовок HTML-файла.
• extratags: Указывает, следует ли интерпретировать расширенные теги. Возможные значения: true (1) или false (0).
• extratags-back: Указывает, следует ли преобразовывать расширенные теги обратно в их исходную форму (например %date%) при преобразовании HTML-содержимого, сгенерированного Markdown Forever, обратно в Markdown. Возможные значения: true (1) или false (0).
• filename: Указывает имя выходного файла при сохранении.
• keywords: Указывает ключевые слова, относящиеся к теме(ам), рассматриваемым в вашем документе.
• lang: Указывает основной язык документа. При необходимости используйте теги span/div с атрибутом lang для указания смены языка внутри документа.
• mathjax: Указывает, следует ли преобразовывать математические формулы, написанные на LaTeX. Возможные значения: true (1) или false (0). Требуется подключение к Интернету, и вы должны открыть преобразованный результат в своём браузере для правильного отображения, поскольку интерпретируемый LaTeX не может быть отображён виртуальным буфером NVDA. Нажмите здесь, чтобы получить дополнительную информацию о MathJax.
• path: Указывает каталог, в котором должен быть сгенерирован документ. Поддерживаются переменные окружения %userprofile%, %appdata% и %tmp%.
• subtitle: Указывает подзаголовок для вашего HTML-документа. Это будет добавлено в заголовок HTML-файла.
• title: Указывает заголовок HTML-документа. В интерактивном режиме поле заголовка будет автоматически заполнено с использованием значения этого ключа.
• toc: Указывает, следует ли создавать оглавление. Возможные значения: true (1) или false (0).

Пример использования метаданных

title: «простой заголовок» date: 2019-11-08 subtitle: «это подзаголовок вашего документа» lang: ru author: • Иван Иванов • Пётр Петров CSS: • %userprofile%/document/main.css • %userprofile%/document/custom.css keywords: NVDA, Markdown, HTML filename: test path: "%userprofile%/desktop" toc: 0 autonumber-headings: 1 mathjax: 0

Привет, мир! Bonjour le monde ! ¡Hola mundo! Xin chào thế giới!

В приведённом выше примере текст будет озвучен на четырёх языках, предполагая, что используемый вами голосовой синтезатор поддерживает автоматическое переключение языка и соответствующий флажок установлен в настройках речи NVDA. Это будет звучать следующим образом (эффект слышен только при использовании многоязычного синтезатора):

Привет, мир! Bonjour tout le monde! ¡Hola mundo! Xin chào thế giới!

Расширенные теги

Расширенные теги — это специальные заполнители, которые вы можете поместить в своё содержимое Markdown для автоматического добавления системной информации, такой как текущая дата или время, которые будут отображаться в виде обычного текста в вашем HTML-документе.

Поддерживаемые расширенные теги

Настройки MarkdownForever по умолчанию

Доступ к ним можно получить из меню NVDA -> Параметры -> MarkdownForever -> Настройки, и они позволяют настроить и установить по умолчанию различные параметры, связанные с процессом преобразования, уже упомянутые выше:

• «Создать оглавление»: Этот флажок позволит вам создавать или не создавать индекс глав вашего итогового HTML-документа с кликабельными ссылками, ведущими к каждой главе. Это поведение также может быть установлено для отдельного документа с помощью ключа «toc» в необязательном блоке метаданных и размещено в любом месте документа с помощью соответствующего расширенного тега.
• «Включить расширенные теги»: Если этот флажок установлен, он включает возможность использования специальных тегов в вашем содержимом Markdown для автоматической вставки таких вещей, как текущая дата или время. Это поведение также может быть установлено для отдельного документа с помощью ключа extratags в необязательном блоке метаданных.
• «Создать соответствующие метаданные из исходного кода HTML»: При преобразовании исходного файла HTML в Markdown предпринимается попытка определить метаданные из исходного кода (заголовок, язык, имя файла и т.д.) и создать для вас блок метаданных.
• «Действие по умолчанию в интерактивном режиме»: Это позволяет выбрать действие по умолчанию, которое будет выполняться при нажатии клавиши Enter в интерактивном режиме: Показать сгенерированное содержимое в браузере, в виртуальном буфере или поместить его в буфер обмена.
• «Движок Markdown»: MarkdownForever позволяет вам выбирать между двумя движками преобразования: HTML2Text и HTML2Markdown. Просто экспериментируйте и выберите тот, который вам больше нравится, в соответствии с вашими потребностями или полученным результатом.
• «Расширения Markdown»: Настройте поддерживаемые функции markdown-it-py (таблицы, списки задач, сноски, идентификаторы заголовков и т.д.).
• «Путь»: Здесь вы можете установить место сохранения по умолчанию на вашем жёстком диске для преобразованных документов. Это удобно, если вы всегда используете одну и ту же папку для хранения всех ваших работ.
• «Управление HTML-шаблонами»: Это откроет диалоговое окно, позволяющее добавлять, редактировать и удалять HTML-шаблоны. С помощью шаблонов вы сможете настраивать визуальные аспекты ваших сгенерированных HTML-документов, используя CSS (каскадные таблицы стилей) — язык, отвечающий за стиль страницы. Это позволит вам изменять цвета, макет или добавлять изображения в ваши работы и создавать шаблоны для каждой конкретной потребности. В интернете, конечно, существует множество руководств по изучению CSS, и это может быть хорошей отправной точкой.

Сводка команд

• NVDA+CTRL+i: Интерактивный режим.
• NVDA+ALT+b: Преобразование Markdown в HTML. Результат отображается в вашем браузере по умолчанию.
• NVDA+ALT+n: Преобразование Markdown в HTML. Результат отображается в виртуальном буфере NVDA.
• NVDA+ALT+k: Преобразование HTML в Markdown. Результат отображается в виртуальном буфере NVDA.
• NVDA+ALT+l: Преобразование Markdown в исходный код HTML. Результат отображается в виртуальном буфере NVDA.
• NVDA+SHIFT+g: Преобразование HTML в Markdown. Результат копируется в буфер обмена.
• NVDA+SHIFT+h: Преобразование Markdown в форматированный HTML. Результат копируется в буфер обмена.
• NVDA+CTRL+h: Преобразование Markdown в исходный код HTML. Результат копируется в буфер обмена.

Информация о дополнении

• Авторы:
  • André <dev@andreabc.net>: создатель и основной сопровождающий дополнения.
  • Sof <hellosof@gmail.com>: документация на английском и французском языках, различные предложения.
  • Victor Cai: китайская локализация.

• Danil Kostenkov <danilkostenkov38@gmail.com>: русская локализация.
  • Çağrı Dogan, Umut Korkmaz: турецкая локализация.
  • Rémy Ruiz <remyruiz@gmail.com>: испанская локализация.
  • Dang Manh Cuong <dangmanhcuong@gmail.com>: вьетнамская локализация.
  • И многие другие!

• Лицензия: GNU General Public License, версия 2
• Скачать стабильную версию
• Скачать разрабатываемую версию
• Репозиторий GitHub: aaclause/NVDA-markdownForever
• Включённые зависимости: