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

Development, Python | Amber | Комментировать запись

Markdown – это язык разметки, обычно используемый для упрощения процесса написания контента в удобном для чтения формате, который программный инструмент или библиотека программирования могут преобразовать в HTML для отображения в браузере или другой программе. Поскольку Markdown использует текстовый синтаксис, он совместим с любым текстовым редактором и может преобразовывать заголовки, списки, ссылки и другие компоненты. Блоггеры, авторы руководств и составители документаций широко используют Markdown. Его поддерживают многие сайты, среди которых Github, StackOverflow и The Python Package Index (PyPI).

Чтобы понять, как использовать Markdown, ознакомьтесь со стандартом синтаксиса Markdown. Также вы можете попробовать другую реализацию Markdown в веб-редакторе, например редактор StackEdit.

Python-Markdown – это библиотека Python, которая позволяет различными способами конвертировать текст Markdown в HTML. Вы можете расширить ее функциональные возможности, используя различные дополнения. Однако имейте в виду, Python-Markdown имеет несколько незначительных отличий от стандартного синтаксиса Markdown.

В этом руководстве мы расскажем, как установить библиотеку Python-Markdown, использовать ее для преобразования строк Markdown в HTML, конвертировать файлы Markdown в файлы HTML и использовать интерфейс командной строки Python-Markdown.

Требования

• Локальная установка Python 3 (вы можете найти в нашем блоге инструкции для разных дистрибутивов: Ubuntu, CentOS, Debian).
• Базовые навыки работы с Python и HTML. Чтобы освежить свои знания, обратитесь к специальным разделам по Python 3 и HTML в нашем блоге.

1: Установка Python-Markdown

Прежде всего мы установим Python-Markdown и изучим одну из его функций для преобразования строк Markdown в HTML в Python REPL.

Читайте также: Использование интерактивной консоли Python

Если вы еще не активировали среду разработки, убедитесь, что вы находитесь в каталоге проекта (здесь он называется pymark), и используйте следующую команду:

source env/bin/activate

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

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

Используйте следующую команду pip для установки библиотеки Python-Markdown (пакет которой называется markdown):

pip install markdown

После успешного завершения установки вы можете поэкспериментировать с ней в интерактивной консоли Python, которую можно открыть с помощью следующей команды:

python

Вы увидите новое приглашение командной строки с префиксом >>>; его можно использовать для ввода кода Python и немедленного получения результата.

Сначала давайте импортируем пакет markdown и используем его для преобразования фрагмента текста Markdown в синтаксис HTML:

import markdown


markdown.markdown('#Hi')

В этом коде мы импортировали ранее установленный пакет markdown. Потом мы использовали функцию markdown.markdown() для преобразования текста Markdown #Hi (где # представляет заголовок уровня H1) в его HTML-эквивалент. Если вы введете код в Python REPL, вы получите следующий вывод:

'<h1>Hi</h1>'

Вывод HTML <h1>Hi</h1> эквивалентен тексту #Hi в Markdown.

Для ввода многострочного текста Markdown в Python REPL вы можете использовать тройные одинарные кавычки (”’). Это делается так:

import markdown

output = markdown.markdown('''

# Step 1

## Step 2

* item 1

* item 2



Visit [the tutorials page](https://www.8host.com/blog/) for more tutorials!

''')



print(output)

В этом примере мы передаем заголовок H1, заголовок H2, два элемента списка и абзац, содержащий ссылку. Затем мы сохраняем вывод в переменной output и выводим его с помощью функции Python print().

Вы получите следующий вывод:

<h1>Step 1</h1>
<h2>Step 2</h2>
<ul>
<li>item 1</li>
<li>item 2</li>
</ul>
<p>Visit <a href="https://www.8host.com/blog/">the tutorials page</a> for more tutorials!</p>

Как видите, на выходе получается HTML-версия введенного в консоль текста Markdown.

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

2: Создание программы для преобразования файлов Markdown в HTML

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

Для начала откройте новый файл Picnic.md, в который мы поместим текст Markdown:

nano Picnic.md

И введите в него следующий Markdown:

# Things to bring

* Food.
* Water.
* Knife.
* Plates.

В этом файле мы видим заголовок H1 и список, который включает четыре элемента.

Сохраните и закройте файл.

Затем откройте новый файл по имени convert.py, содержащий код для преобразования файла Picnic.md в файл HTML:

nano convert.py

Введите в него следующий код Python:

import markdown

with open('Picnic.md', 'r') as f:
    text = f.read()
    html = markdown.markdown(text)


with open('Picnic.html', 'w') as f:
    f.write(html)

Мы сначала импортировали пакет markdown. После этого мы использовали функцию open(), чтобы открыть файл Picnic.md; передавая значение ‘r’ в качестве второго параметра, мы указываем, что Python должен открыть файл для чтения.

Затем мы сохраняем файловый объект в переменной f, которую можно использовать для ссылки на файл. Потом программа читает файл и сохраняет его содержимое в переменной text. После этого она конвертирует текст с помощью markdown.markdown(), сохраняя результат в переменной html.

Используя тот же шаблон, мы открываем новый файл по имени Picnic.html в режиме записи (о чем сообщает значение ‘w’) – обратите внимание, что этот файл еще не существует – и записываем в него содержимое переменной html. Это действие создаст и сохранит в вашей системе новый файл. Оператора with при открытии файла гарантирует, что Python закроет его после завершения обработки.

Сохраните и закройте файл convert.py.

Затем запустите нашу новую программу:

python convert.py

Она создаст в каталоге вашего проекта новый файл Picnic.html со следующим содержимым:

<h1>Things to bring</h1>
<ul>
<li>Food.</li>
<li>Water.</li>
<li>Knife.</li>
<li>Plates.</li>
</ul>

Теперь, когда вы знаете, как конвертировать файлы Markdown с помощью функции markdown.markdown(), вы можете сгенерировать текст Markdown в Python и преобразовать эти файлы без их предварительного чтения.

3: Генерирование файлов Markdown и их преобразование в HTML

В этом разделе мы создадим программу, которая генерирует текст Markdown из словаря Python, сохраняет его в файл Markdown и преобразует этот текст в файл HTML с помощью функции markdown.markdownFromFile().

Эта программа сгенерирует файл Markdown cities.md со списком стран и их тремя крупнейшими городами. После этого программа преобразует сгенерированный текст Markdown в HTML, а затем сохранит HTML в файл cities.html.

Для начала откройте новый файл Python, citygen.py:

nano citygen.py

Затем добавьте в него следующий код:

import markdown



country_cities = {'Japan': ['Tokyo', 'Osaka', 'Nagoya'],
                  'France': ['Paris', 'Marseille', 'Lyon'],
                  'Germany': ['Berlin', 'Hamburg', 'Munich'],
                  }

Сначала мы импортируем в этом файле библиотеку Python-Markdown, а затем определяем словарь country_cities, содержащий несколько стран (в качестве ключей) и список из трех крупнейших городов для каждой страны (в качестве значения). Этот словарь – просто пример структуры данных; вы можете заменить его любыми другими данными: данными, полученными из веб-API, базы данных или любого другого источника.

После словаря добавьте следующий код:

. . .
with open('cities.md', 'bw+') as f:
    for country, cities in country_cities.items():
        f.write('# {}\n'.format(country).encode('utf-8'))
        for city in cities:
            f.write('* {}\n'.format(city).encode('utf-8'))
    f.seek(0)
    markdown.markdownFromFile(input=f, output='cities.html')

После словаря мы используем синтаксис with open(…) as…, чтобы открыть файл по имени cities.md, которого пока что не существует. Мы открываем его в двоичном режиме (‘b’) для записи и чтения (‘w+’). Мы используем двоичный режим, потому что если мы передадим строку в markdown.markdownFromFile(), она будет интерпретирована как путь к читаемому файлу в файловой системе (то есть ‘/home/file.md’). Также двоичный режим позволяет избежать проблем, связанных с преобразованием символов в платфомно-зависимое представление. Это гарантирует, что программа Python будет вести себя одинаково на любой платформе.

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

Внутри первого цикла программа записывает название страны в новый файл cities.md в заголовке # (что равно HTML-тегу <h1>). \n – специальный символ для вставки новой строки. Мы используем здесь .encode(), потому что мы открыли файл в двоичном режиме. Второй цикл for проходит по городам и записывает их названия в файл Markdown как элемент списка * (что отвечает HTML тегу <li>).

После завершения первого цикла код перемещается в конец файла, что означает, что markdown.markdownFromFile() не сможет прочитать его содержимое; поэтому мы используем f.seek(0), чтобы вернуться в начало файла. Объект f передается в markdown.markdownFromFile() в качестве входных данных, чтобы программа могла преобразовать его в HTML и сохранить в новый файл cities.html.

Сохраните и закройте файл.

Давайте запустим программу citygen.py:

python citygen.py

Эта команда сгенерирует два файла.

Первый – это city.md, файл Markdown со следующим содержимым:

# Japan
* Tokyo
* Osaka
* Nagoya
# France
* Paris
* Marseille
* Lyon
# Germany
* Berlin
* Hamburg
* Munich

Второй файл – это cities.html, HTML-файл, содержащий результат преобразования содержимого cities.md:

<h1>Japan</h1>
<ul>
<li>Tokyo</li>
<li>Osaka</li>
<li>Nagoya</li>
</ul>
<h1>France</h1>
<ul>
<li>Paris</li>
<li>Marseille</li>
<li>Lyon</li>
</ul>
<h1>Germany</h1>
<ul>
<li>Berlin</li>
<li>Hamburg</li>
<li>Munich</li>
</ul>

Вы также можете использовать функцию markdown.markdownFromFile() для преобразования существующего файла Markdown. К примеру, мы могли бы преобразовать файл Picnic.md в файл по имени Picnic-out.html, используя следующий код:

import markdown

markdown.markdownFromFile(input='Picnic.md', output='Picnic-out.html')

Также функцию markdown.markdownFromFile() можно использовать для прямого преобразования файла, если файл не нуждается в каких-либо изменениях. Если же вам нужно изменить файл Markdown, вы можете прочитать его, а затем преобразовать, используя метод, продемонстрированный в разделе 2.

Итак, мы преобразовали текст Markdown в HTML с помощью Python. Однако Python-Markdown также предоставляет полезный интерфейс командной строки (CLI) для быстрого преобразования файлов Markdown в HTML – мы рассмотрим этот инструмент на следующем шаге.

4: Использование командной строки Python-Markdown

На этом этапе мы посмотрим, как работает интерфейс командной строки Python-Markdown и как использовать его для преобразования файла Markdown в HTML и отображения вывода или сохранения его в файл HTML.

Чтобы запустить сценарий командной строки Python-Markdown, используйте флаг –m – он запускает модуль библиотеки как сценарий. Например, чтобы преобразовать файл Markdown, вы можете передать его команде markdown следующим образом (замените filename.md именем файла, который вы хотите преобразовать):

python -m markdown filename.md

При выполнении этой команды на экране появится HTML-код для текста Markdown, который хранится в файле filename.md.

Допустим, чтобы преобразовать файл Picnic.md, нужно выполнить следующую команду:

python -m markdown Picnic.md

Она отобразит следующий вывод:

<h1>Things to bring</h1>
<ul>
<li>Food.</li>
<li>Water.</li>
<li>Knife.</li>
<li>Plates.</li>
</ul>

Чтобы сохранить вывод в файл по имени output.html, используйте команду:

python -m markdown Picnic.md -f output.html

Теперь вы умеете использовать интерфейс командной строки markdown для преобразования файлов Markdown в HTML.

Заключение

В этом руководстве вы научились использовать Python для преобразования текста Markdown в HTML. Теперь вы можете писать свои собственные программы Python, которые используют синтаксис Markdown в различных контекстах (например, веб-приложения, использующие веб-фреймворк типа Flask или Django).

Чтобы узнать больше о том, как работает Markdown, посетите его веб-сайт. Дополнительные инструкции по использованию Markdown с Python вы найдете в документации Python-Markdown.

Вот несколько расширений, официально поддерживаемых Python-Markdown:

• Extra: предоставляет дополнительные функции к стандартному синтаксису Markdown, например, определение сокращений, добавление атрибутов к различным элементам HTML, сноски, таблицы и многое другое.
• CodeHilite: добавляет поддержку выделения синтаксиса к блокам кода.
• Table of Contents: создает оглавление на основе документа Markdown и добавляет его в итоговый документ HTML.