Skip to content
Web Dev

Styling Markdown

Writing blog posts in markdown is great. It’s simple and fast.
Markdown is a simple way to write text using common symbols to add things like **bold**, *italics*, or lists. 1

Many webpages have their content written in markdown. The markdown content gets then transformed into HTML that is displayed on the website. But when you are building your own website you will also want to style that content, so how could that look like?

On styling content written in markdown

There are multiple ways you can approach styling your own markdown content.

Because I’d like my written contents design to fit into the rest of the page I like to write my own styles. This is a bit of work though as we have to write styling for the various elements that markdown allows us to create.

Part of your styling such as <p> and <h1> elements might already have styling defined in your main CSS file that you can continue to use. But markdown content can also include images, code blocks, quotes, tables and more which we have to take care of.

Styling the different elements

I will asume that the html should look something like this:

<main>
    <div class="markdown-container">
        <slot /> <!-- //Markdown content iserted here -->
    </div>
</main>

Note: Using main or article is okay.
To this container we want to apply some styling as well as on all its children like this:

.markdown-container {
    width: min(100% - 2rem, 700px);
}
.markdown-container > *:not(:first-child) {
    margin-block-start: 1.5em;
}

To space the elements I give all direct children of the container except for the first a margin-top of 1.5em.

The markdown-container will have a max width of 700px, or smaller for mobile devices. The keyword min selects the smaller amount. You might also want to make the container into a flex-box or grid depending on how you want to control your layout.

Parapgraph <p>

We want the content that gets brought in through markdown to match the already existing content of the website. Which means we want to already have defined CSS variables in the root and applied styling to elements such as the body for text. I have explained how CSS variables should be used here: CSS Variables.

Which means we already should have something similar to this:

:root {
    --variable-1: ...
}


body {
    font-family: ui-sans-serif, "Source Sans Pro", "Helvetica", system-ui;
    line-height: 1.75;
    color: hsl(224, 20%, 97%);
    background-color: hsl(216, 28%, 7%);
}

This should take care of all <p> elements without needing to further style them excplicitly.

Section Headings <h1>, <h2> ..

Section headings are of major importance since they got used often and important for keeping an overview. !!!

h1, h2, h3, h4, h5, h6 {
    margin-block-start: 2em;
    overflow-wrap: anywhere;
}

You might also want to set a line-height, font-weight and color for your section heading elements.

The Font-size for each section heading should also be set, it makes sense to do this in via CSS variables to make heading sizes uniform. If you are looking for specific font sizes to use check out CSS variables.

Images <img> & <picture>

img, picture {
    object-fit: scale-down;
    max-width: 100%;
    height: auto;
    border-radius: 0.25rem;
    margin-inline: auto;
    display: block;
}

Object-fit: scale-down makes sure we can always see the full picture. By setting max-width and height we ensure proper sizing of the image. Border-radius to set slightly rounded corners.

If you are using a framework like Astro, to center the image you will want to add margin-inline: auto and display: block to center the image.

Lists

Ordered and unordered

ol, ul {


}
li {
    overflow-wrap: anywhere;
}

Quote

Table

Code & Code Block

  • overflow-wrap: anywhere
  • font-family: mono font

hr

hr {
    border: 0;
    border-bottom: 1px solid var(--color-side-1);
}

Last words

Text here

Sources & References

Footnotes

Footnotes

  1. Markdown cheat sheet: https://www.markdownguide.org/cheat-sheet/ ↩