Image & Text Alignment as Separate Sections?

[eXpl0it3r]

We're migrating our currently handwritten HTML pages to Markdown and consider MkDocs Material as a potential static site generator.

Maybe the wanted look isn't possible, but I thought, I rather ask before thinking of potential other options.

This is what we currently have. Not the image + text always being neatly packed next to eachother:

This is what I've managed so far with { align=right } / { align=left }, but as you can see the text will just naturally flow into the previous section.

It's not as bad here, but gets worse if the texts are even shorter or there's no image to match.

Is there somehow a way in Markdown or with extension syntax to specify that this should really be considered its own "row" of content?

# Simple and Fast Multimedia Library

![multi-media](images/home/multimedia.png){ align=right }

## SFML is multi-media

SFML provides a simple interface to the various components of your PC, to ease the development of games and multimedia applications. It is composed of five modules: system, window, graphics, audio and network.

Discover their features more in detail in the tutorials and the API documentation.

![multi-platform](images/home/multiplatform.png){ align=left }

## SFML is multi-platform

With SFML, your application can compile and run out of the box on the most common operating systems: Windows, Linux, macOS and Android & iOS (with limitations).

Pre-compiled SDKs for your favorite OS are available on the download page.

![multi-language](images/home/multilanguage.png){ align=right }

## SFML is multi-language

SFML has official bindings for the C and .Net languages. And thanks to its active community, it is also available in many other languages such as Java, Ruby, Python, Go, and more.

Learn more about them on the bindings page.

[squidfunk]

You could wrap your headlines in block level elements, e.g. divs, which should achieve the desired effect.

[alexvoss]

You may want to use Markdown in HTML. Note that the markdown attribute needs to be set on each HTML element that contains Markdown to be parsed and that you need to be careful with indentation. Best to keep the hierarchy quite flat and not indent the HTML as you might otherwise do.

[eXpl0it3r]

@alexvoss thanks for the hint regarding Markdown in HTML, I was already confused why it wasn't being rendered. 😄

The result isn't much different, but this would in theory allow me to write some CSS class to fix the alignment issue. It seems that due to the align of the image, the div doesn't consider the full height of the image for the div, so only the text height is considered and thus the next section flows into the previous section again.

[alexvoss]

You may want to look at CSS grid layout for this, I think.

[eXpl0it3r]

Yeah, will have to see. Kind of want to use as little raw-HTML as possible and also got to consider mobile views for everything.

This is at least a good starting point:

<div markdown="1">
![multi-media](images/home/multimedia.png){ align=right }

## SFML is multi-media

SFML provides a simple interface to the various components of your PC, to ease the development of games and multimedia applications. It is composed of five modules: system, window, graphics, audio and network.

Discover their features more in detail in the tutorials and the API documentation.

</div>

With Markdown in HTML active in mkdocs.yml:

markdown_extensions:
  - md_in_html

[alexvoss]

There is a limit to what can be achieved with pure Markdown, so some HTML is often necessary. There is a Markdown way to create HTML tags in the Python Markdown Extensions but I am not sure it is better than using HTML tags. May be a question of taste.