Have two columns in Markdown

Question

I would like to write a coding standard specification document with good and bad coding examples. Each rule should have a number, a description and an example.

For example here is the rule 1:

# Rule 1
Description for rule 1.

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

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

From each rule, I would like to generate a PDF or an HTML page with a global table of contents.

How can I write a Markdown compatible code that can represent horizontally aligned code blocks with syntactic coloring?

Like this (this is an image):

I know that I could use HTML inside my Markdown document, so I might be able to write something like this:

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

And process the data afterwards (I still don't know how)

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

Is there a better way to horizontally align two blocks of code horizontally?

Drawn

might be related: stackoverflow.com/editing-help#tables - but only applied to SO Documentation pages... – Paz

Answer 1

You can't, at least not with pure Markdown as it doesn't have any concept of columns. As explained in the rules:

The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

In fact, the best way would be to have each code block wrapped in a <div> with the appropriate class assigned to each div. However, most Markdown parsers do not parse Markdown inside a raw HTML block. Therefore, you may need to also define the code block in raw HTML as well. Check your parser's list of features to find out. In the event you are not able to define your own CSS to use separately from the Markdown (to style the HTML), you will also need to define the styles inline in the HTML. This question includes a nice sample of what that might look like. Just replace the comments with the appropriate code blocks. If you have to define your code blocks in raw HTML, they would look like this:

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

So, the final document that is sure to work in all (most?) Markdown parsers would look like this:

# 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>

Note that that uses one of many different ways of defining columns in CSS. Different methods may or may not work in different browsers. YMMV.

Electrolyse

Answer 2

While this doesn't work for all dialects of Markdown, I got this to work with GitLab, GitHub, and mdBook.

Basically, you create the table via HTML. Markdown and HTML don't mix well, but if you surround the Markdown with whitespace, sometimes the Markdown can be recognized.

https://docs.gitlab.com/ee/user/markdown.html#inline-html

<table>
<tr>
<th> Good </th>
<th> Bad </th>
</tr>
<tr>
<td>

```c++
int foo() {
    int result = 4;
    return result;
}
```

</td>
<td>

```c++
int foo() { 
    int x = 4;
    return x;
}
```

</td>
</tr>
</table>

Deaf

Doesn't work in Typora, for the record – Sattler

Works in Codeberg.org README files which is based on Gitea. – Yoon

Works in GitHub, but can't use styles because they're filtered out by GH, so the results are usually hideous. github.github.com/gfm/#disallowed-raw-html-extension- – Cimon

Works in a Databricks notebook Markdown cell. – Tazza

works in mkdocs – Fallen

Does not work in the Hashnode blog. It shows the columns but they are single rows allowed only. – Unstop

Answer 3

This is an old question but in case people come here from Google, the above answer is correct for plain true Markdown, but if you're looking to do this with or through something that's implementing kramdown, kramdown does support mixed HTML and Markdown syntaxes by its usage of PHP Markdown Extra as noted in kramdown docs here. kramdown just requires that in your markdown page where you intend to use said HTML, you add an attribute to the wrapping HTML element of markdown="1".

As an example (and direct solution to two-column markdown), this results in two columns for content. I did this using Bootstrap to handle both column width and image centering, but you could take any approach for those topics.

<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>

Be wary of indents. I specifically didn't indent more than one level in the above code. I believe kramdown by default will interpret doubly-indented code as a quote block (and if I recall correctly, that's standard for Markdown in general).

Also note that I chose to use the html img tag instead of the markdown image link. You may choose to do the same since you gain a bit of extra control.

And, if you're new or unfamiliar with/to Bootstrap, you can change the relative column widths by changing the 8 and/or 4 shown in the code above, just make sure the sum of those two numbers is always 12.

As mentioned above, this only works for markdown consumers implementing the kramdown engine (and that's great for Jekyll users).

Shalondashalt

Answer 4

A non HTML approach using Latex multicol is as follows (inspired by this answer)

    ---
    header-includes:
        - \usepackage{multicol}
        - \newcommand{\hideFromPandoc}[1]{#1}
        - \hideFromPandoc{
            \let\Begin\begin
            \let\End\end
          }
    ---
    
    # Rule 1
    Description for rule 1.
    
    \Begin{multicols}{2}
    ## Good
    ```c
    int foo (void) 
    {
        int i;
    }
    ```
    
    ## Bad
    ```c
    int foo (void) {
        int i;
    }
    ```
    \End{multicols}

which exports correctly with pandoc

Additionally, you may need to use \Begin{minipage} and \End{minipage} if you multicols doesn't divide the columns correctly (can happen if there are nested subheaders)

Grapeshot

Thanks. Worked like a charm, right through to the generated PDF. – Rheostat

Answer 5

Depending on what flavour of markdown you're using, if you're using R Markdown at least, you can use the ::: format to create multi-column layouts. Much simpler than embedding HTML etc..

The ::: is shorthand for a tag, but unlike adding a raw HTML, the ::: can wrap code blocks etc. to keep everything in the R markdown framework.

The ::: must be followed by {} containing any declarations you would put inside the opening tag, or empty if there are none, but it must be there (ie :::{}).

Here, you can add any css styling or classes, even bootstrap to make your markdown responsive:

::: {.row}
  ::: {.col-md-4}
    table ...
  :::
  ::: {.col-md-8}
    graph ...
  :::
:::

You can find more detail at https://enzedonline.com/en/tech-blog/adding-multi-column-formats-to-r-markdown-documents/

Example:

```{r, fig.height=4, fig.width=5, warning=FALSE, message=FALSE}
library(ggthemes)
library(kableExtra)
library(ggplot2)
library(dplyr)
data("mtcars")
```
:::::::::::::: {.columns}
::: {.column width="30%"}

```{r}
mtcars %>% 
    select(disp, mpg) %>% 
    sample_n(10) %>% 
    kbl() %>% 
    kable_styling()
```

:::
::: {.column width="5%"}

\

:::
::: {.column width="65%"}


\

```{r, fig.height=4, fig.width=7}
mtcars %>% 
    ggplot(aes(x=disp, y=mpg)) +
    geom_point() +
    theme_excel_new()
```

:::
::::::::::::::

Gives the following output:

Isothere

Not sure I get it. First of all, this is in R? To compute and render those graphics, right? Second, what does : and ` do? If I understood, several :` marks begining and ending, and ::: separate columns. – Pandybat

@BernardoDalCorno it's R Markdown (R in the code blocks generating the table and graphics). The ::: notation is a kind of shorthand for <div> in R markdown. The extra long ones at start and end don't need to be long, it just helps (me) with readability. – Isothere

Answer 6

With HTML and ```, you can do use the power of both columns and syntax coloring:

<div style="text-align: center; display: grid; grid-template-columns: 1fr 1fr;">
  <div>parent

```html
<component>content</component>
```

  </div>
  <div>
child

```html
<slot>fallback content</slot>
```

  </div>
</div>

Pandybat

Answer 7

Although originally intended to show the difference between two code blocks, given its green and red highlighting Markdown diff can be used also to show good and bad coding examples. For example the following code:

```diff
+ int foo (void) 
+ {
+     int i;
+ }
- int foo (void) {
-     int i;
- }
```

would show up as:

Metonymy

Answer 8

I don't know who else wanders here after so much time but heres an idea I used. Just simply set the parent element's display to grid.

setting parent style to:

 width: 100%;
 display: grid;
 grid-template-columns: repeat(1, 1fr);
 gap: 1rem;

will make your Markdown loader fill the grids on order.

Loading this:

# Some title

Some text here.

[image]

More text.

Fill in like this:

 _______________________________
| Some title   | Some text here.|
 _______________________________
| image        | More text.     |
 _______________________________

It might be useful to use   for example leaving 1-1 grid empty.

And now that you have a parent component you can style it's children to a certain extent.

Forcer