Код двух столбцов в Markdown

Я хотел бы написать документ, который объясняет стандарт кодирования хорошими и плохими примерами кодирования. Каждое правило имеет число описание и пример.

Например, это правило 1:

# Rule 1
Description for rule 1.

## Good
```c
int foo (void) 
{
    int i;
}
```

## Bad
```c
int foo (void) {
    int i;
}
```

Из каждого отдельного правила я хотел бы создать PDF-страницу или HTML-страницу с глобальным оглавлением.

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

Вот так:

Или это:

          Good               Not Good
.---------------------+--------------------.
| int foo (void)      | int foo (void) {   |
| {                   |    int i;          |
|    int i;           | }                  |
| }                   |                    |
'---------------------+--------------------'

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

<good>
```c
int foo (void) 
{
    int i;
}
```
</good>
<bad>
```c
int foo (void) {
    int i;
}
```
</bad>

И обрабатывать данные впоследствии (я до сих пор не знаю, как)

markdown -> own-tags-processing -> LaTeX -> pdf
markdown -> own-tags-processing -> HTML

Есть ли лучший способ горизонтального выравнивания двух блоков кода по горизонтали?

Ответ 1

Вы не можете, по крайней мере, не с чистым Markdown, поскольку у него нет понятия столбцов. Как описано в правилах:

Идея Markdown заключается в том, чтобы упростить чтение, запись и редактирование прозы. HTML - формат публикации; Markdown - это формат записи. Таким образом, синтаксис форматирования Markdowns разрешает проблемы, которые могут передаваться в виде простого текста.

Для любой разметки, которая не покрывается синтаксисом Markdowns, вы просто используете HTML.

На самом деле лучшим способом было бы иметь каждый блок кода, завернутый в <div>, с соответствующим классом, назначенным каждому div. Однако большинство маркерных парсеров не анализируют Markdown внутри необработанного HTML-блока. Поэтому вам может понадобиться также определить блок кода в необработанном HTML. Проверьте свой список парсеров, чтобы узнать. В случае, если вы не можете определить свой собственный CSS для использования отдельно от Markdown (для стиля HTML), вам также необходимо будет определить стили, встроенные в HTML. Этот вопрос содержит хороший образец того, что может выглядеть. Просто замените комментарии соответствующими блоками кода. Если вам нужно определить свои блоки кода в необработанном HTML, они будут выглядеть так:

<pre><code class="language-c">int foo (void) 
{
    int i;
}
</code></pre>

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

# Rule 1
Description for rule 1.

<div style="-webkit-column-count: 2; -moz-column-count: 2; column-count: 2; -webkit-column-rule: 1px dotted #e0e0e0; -moz-column-rule: 1px dotted #e0e0e0; column-rule: 1px dotted #e0e0e0;">
    <div style="display: inline-block;">
        <h2>Good</h2>
        <pre><code class="language-c">int foo (void) 
{
    int i;
}
</code></pre>
    </div>
    <div style="display: inline-block;">
        <h2>Bad</h2>
        <pre><code class="language-c">int foo (void) {
    int i;
}
</code></pre>
    </div>
</div>

Обратите внимание, что это использует один из многих способов определения столбцов в CSS. Дифференцированные методы могут работать или не работать в разных браузерах. YMMV.

Ответ 2

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

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

<div class="row">
  <div class="col-md-8" markdown="1">
  Some text.
  </div>
  <div class="col-md-4" markdown="1">
  <!-- ![Alt Text](../img/folder/blah.jpg) -->
  <img height="600px" class="center-block" src="../img/folder/blah.jpg">
  </div>
</div>

Остерегайтесь отступов. Я специально не делал отступ более одного уровня в приведенном выше коде. Я считаю, что kramdown по умолчанию будет интерпретировать код с двойным отступом как блок кавычек (и, если я правильно помню, этот стандарт для Markdown в целом).

Также обратите внимание, что я решил использовать тег html img вместо ссылки на изображение уценки. Вы можете сделать то же самое, поскольку получаете немного дополнительного контроля.

И, если вы новичок или незнакомы с/в Bootstrap, вы можете изменить относительную ширину столбца, изменив 8 и/или 4 показанные в коде выше, просто убедитесь, что сумма этих двух чисел всегда равна 12.

Как упомянуто выше, это работает только для потребителей уценки, реализующих движок kramdown (и это отлично подходит для пользователей Jekyll).