Вставка необработанного HTML в Markdown

Безопасный ответ заключается в использовании следующего:

<div class = "aside">
<h2>My heading</h2>
<p>Some text, some text, some more text.</p>
</div>

Однако это сложнее, чем со многими возможными ответами. Какой ответ относится к вам, зависит от того, какую реализацию Markdown вы используете, поскольку между ними есть тонкие различия. Давайте начнем с эталонной реализации (markdown.pl) и оригинальные правила, так как Hoedown утверждает, что следует им (см. ниже).

Уценка старой школы

Многие из старых синтаксических анализаторов были впервые разработаны во время перехода от HTML4 к XHTML1, и их поведение и обработка необработанного HTML отражают это. Тем не менее, некоторые из них были обновлены в последние годы, чтобы добавить поддержку новых функций HTML. Однако эталонная реализация не обновлялась более десяти лет и является хорошей отправной точкой. Как правило, если вы можете заставить что-то работать в эталонной реализации, это будет работать в любой реализации, так что давайте сосредоточимся на этом.

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

Естественно, при использовании тегов уровня диапазона вы хотите, чтобы результат был заключен в теги <p>. Например, foo <i>bar</i> baz должно привести к <p>foo <i>bar</i> baz</p>. Таким образом, чтобы избежать оборачивания необработанного HTML-кода в теги <p>, существует очень специфический набор обстоятельств, которые требуют правила:

The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

Там 3 требования:

1. Блок необработанного HTML должен начинаться с известного тега уровня блока. Как было установлено ранее, в более старых реализациях эти теги должны быть допустимыми тегами блочного уровня в спецификациях HTML4/XHTML1. Все, что недавно было представлено в HTML5, может не работать последовательно в разных реализациях.
2. Открывающему тегу должна предшествовать пустая строка или начало документа, а закрывающему тегу должна следовать пустая строка или конец документа.
3. Открывающий тег должен начинаться с первого символа строки. Любой отступ приведет к тому, что синтаксический анализатор не сможет распознать блок текста как необработанный HTML на уровне блока.

Наконец, правила гласят:

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Обратите внимание, что это отличается от HTML на уровне диапазона:

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

В этом случае <span>foo *bar*</span> приводит к <p><span>foo <em>bar</em></span></p>, а <div>foo *bar*<div> приводит к <div>foo *bar*</div>. Обратите внимание, что в первом примере при обработке синтаксиса Markdown (*bar*) все было заключено в теги <p>. Наоборот. во втором примере синтаксис Markdown (*bar*) не обрабатывался, но блок не был обёрнут в теги <p>. Следовательно, любой контент, заключенный в необработанный HTML на уровне блоков, должен быть полностью в необработанном HTML.

Итак, давайте применим эти правила к вашему примеру:

<div>
<aside>
<h2>My heading</h2>
<p>Some text, some text, some more text.</p>
</aside>
</div>

<div> предоставляет тег, который распознается более старыми реализациями. И весь контент представляет собой необработанный HTML, так как он все равно не будет обрабатываться как Markdown. Бабельмарк показывает, что это работает во всех реализациях.

Конечно, использование обоих тегов <aside> и <div> избыточно, поэтому вы можете просто использовать тег <div> с назначенным ему соответствующим классом:

<div class = "aside">
<h2>My heading</h2>
<p>Some text, some text, some more text.</p>
</div>

Как и Babelmark показывает, это работает везде.

Если вы используете реализацию, в которую добавлена ​​поддержка тегов блочного уровня HTML5, вы можете <aside> пометить напрямую:

<aside>
<h2>My heading</h2>
<p>Some text, some text, some more text.</p>
</aside>

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

Расширенная уценка

За прошедшие годы многие реализации Markdown добавили в синтаксис нестандартные расширения, добавляющие дополнительные функциональные возможности. По понятным причинам многие пользователи хотели бы иметь возможность обрабатывать синтаксис Markdown в необработанных блоках HTML. Поэтому много лет назад PHP Markdown Extra представил был markdown = "1" обходным путем, который был скопирован многими реализациями. Однако в большинстве реализаций, поддерживающих расширение, расширение должно быть явно включено. Он не включен по умолчанию.

Если вы используете реализацию, которая поддерживает расширение, и расширение включено, вы можете использовать это (если поддерживаются более новые теги HTML5):

<aside markdown = "1">
## My heading
Some text, some text, some more text.
</aside>

Или это (если теги HTML5 не поддерживаются):

<div markdown = "1">
<aside>
## My heading
Some text, some text, some more text.
</aside>
</div>

или...

<div class = "aside" markdown = "1">
## My heading
Some text, some text, some more text.
</div>

Общий знак

Некоторые люди были разочарованы несоответствиями между реализациями и решили определить строгую спецификацию, которая стала известна как Commonmark. Однако Спецификация общего знака, по собственному признанию, нарушает некоторые очень четко определенные правила исходной реализации. Как ни странно, это только добавило больше несоответствий. Одним из худших нарушений является обработка необработанного HTML.

Пока ваш необработанный HTML-блок не содержит пустых строк, Commonmark будет обрабатывать ваш блок так же, как и реализации старой школы Markdown. Однако, как только вы введете пустую строку, все, что следует за этой пустой строкой, будет проанализировано как Markdown.

Кроме того, спецификация Commonmark четко определяет полный список тегов, которые считаются тегами блочного уровня. Так получилось, что <aside> есть в списке тегов.

Поэтому, если вы используете совместимую реализацию Commonmark, будет работать следующее:

<aside>

## My heading
Some text, some text, some more text.

</aside>

Обратите внимание, что за тегом <aside> сразу следует пустая строка, которая указывает синтаксическому анализатору обрабатывать любое содержимое тега, следующего за ним, как Markdown. Как и Babelmark демонстрирует, это работает с реализациями Commonmark, но не с реализациями старой школы.

Худаун

В частности, Hoedown претензии должен быть «полностью совместимым со стандартами» с «официальными наборами тестов Markdown v1.0.0 и v1.0.3». Обратите внимание, что это наборы тестов для эталонной реализации старой школы, а не для более новой спецификации Commonmark. В таком случае мы можем предположить, что прием Commonmark для обработки Markdown в необработанных блоках HTML не сработает. Конечно, вы можете попробовать, чтобы убедиться.

Hoedown также утверждает, что имеет «дополнительную поддержку нескольких (неофициальных) расширений Markdown». Однако нет ни полного списка доступных расширений, ни инструкций по их включению. У меня не установлен этот инструмент, но, возможно, есть инструкции, доступные из командной строки? Если вы можете найти способ включить расширение markdown = "1", вы можете использовать этот трюк, чтобы получить обработку Markdown в ваших необработанных блоках HTML.

Однако без какой-либо четкой документации я предполагаю, что Hoedown — это реализация старой школы. Я также заметил, что файл html_block_names.gperf в репозитории не указан aside как известный HTML-тег блочного уровня. Поэтому мы можем предположить, что любые необработанные блоки HTML должны быть заключены в один из 24 тегов, перечисленных в этом файле.

Учитывая вышеизложенное, можно смело предположить, что единственным верным способом получения желаемых результатов от Hoedown является следующий:

<div>
<aside>
<h2>My heading</h2>
<p>Some text, some text, some more text.</p>
</aside>
</div>

или...

<div class = "aside">
<h2>My heading</h2>
<p>Some text, some text, some more text.</p>
</div>