I wanted to get some insights into the recommended way to format text and images inside markdown. What I mean is, is it acceptable to use html inside of markdown. I just started using jekyll and I love its simplicity and the ease of using variables on a page.
I am doing my portfolio and for a client page, I’d like to add some text and images. I am using bootstrap to lay them out.
I almost feel like I am doing something wrong but I’ve downloaded some nice themes and indeed they do add html tags within the markdown also. I probably already know the answer but wanted to make sure.
Yes that’s fine. There are some things not possible or practical in markdown so write them as html in a .md file
E.g.
## Heading
<div align="center">
<img src="..." height="100" />
</div>
- bullet
- list
- in
- markdown
The html above sets the size and alignment for an image which work in jekyll between the markdown above and below. I would normally use CSS but the example is actually what I put in a Github README.md file where CSS doesn’t work.
Another example is where you need to build up a bullet list or table using html and a for loop. And if you did it in markdown it would be less readable and you’d have to dedent everything to avoid it becoming code. Plus some empty lines would become markdown and mess with your structure when html tags which don’t care about white space lines work better
Another case is where I want to add a class or ID to an item in a markdown file.
I use a bootstrap jekyll theme which is actually mostly html in order to make use of bootstrap classes.
Then content comes from a data file and is inserted into the rendered html. Separating content and appearance like this is also great because you can add a CMS layer to manage text fields or array fields and not worry about the html structure or classes
A common flow across most Jekyll projects is to have content files at the root as .md using almost all markdown. and then layouts and includes files (macros) as .html - which only have html in them.
Then the layouts are referenced in metadata of contents pages to give them style.
and the includes files are referenced in a layout (such as a google analytics snippet in head) or in a content page (such as an image gallery) to insert snippets.
So you’ll mix html and markdown in separate files and they get rendered together and you can mix html and markdown in a single .md file as per my first comment
Here is my project aimed at beginners of Jekyll. Made using the quickstart project and plenty of intro docs. I also cover using html inside a .md file there.
I wrote this guide specifically for html in markdown:
My project is just a Jekyll site that uses minima theme so you can use template/ fork my project or run it locally or just use it as a reference. The content is mostly from the jekyll quickstart so I added value by adding docs and making it use make.
