by ryanwhocodes

How to style your webpage or markdown like a Medium article — or however you want

The full source code for this tutorial can be found here.

If you love Medium’s style, then you can style your webpages or markdown files (converted to HTML) to give them the visual flavor of a Medium article. This tutorial will cover:

To give you an overview of how the design would look before and after the style has been applied, have a look at the images below.

  • The original Readme (below left)
  • With added style and hosted on Github pages (below right)
View the respective pages at: and

Converting markdown to HTML

There are numerous ways to convert a markdown file, such as a Readme, into HTML. One way is to use a static site generator, such as Middleman or Jekyll.

Get started with Middleman at

Middleman is based on Ruby and inspired by the design of Ruby on Rails. It integrates with markdown parser gems, such as Redcarpet. Once you’ve started a site, include redcarpet in your Gemfile, then add the following to the config.rb of your project:

set :markdown_engine, :redcarpetset :markdown,    :fenced_code_blocks => true,    :smartypants => true,    tables: true,    with_toc_data: true

Next, ensure that your markdown files are within the project source folder, then serve or build the site to render them as HTML.

Get started with Jekyll at

Jekyll has builtin integration with Github pages, and so can be convenient if you want something hosted on Github with minimal design and setup. Once you have set up your site, you can simply include your markdown files and they will be converted to HTML during the build process.

For more on this, have a look at the article Convert an HTML site to Jekyll.

Once you have created the HTML files, take a look at the code. This will show you which HTML tags are used in your page, which you can target for your styling.

Choosing custom fonts

You can find similar fonts to Medium on sites like Google fonts. Find a sans-serif font for your headings and a serif font for the body text. Below are a few suggestions:

The quickest way to add them is through a link in your HTML head or CSS file. However, hosting the fonts locally means you can be independent of an external download service. One great tool is the Google Webfont Helper, which not only provides font downloads but also the CSS to load them into your stylesheets. Now you can add the fonts for the headings and body elements to your stylesheet.

h1, h2, h3, h4, h5, h6 {  font-family: 'Open Sans', sans-serif;}
p, ul, li, a {    font-family: 'Lora', serif;}

Styling with CSS and Sass

Vanilla CSS is a good choice for small web pages and sites. For larger projects, a CSS pre-compiler, such as Sass, means you can build your CSS with features such as partials and shared variables.

Get started with Sass at

If you want to define all your key values in one file that is shared across your other stylesheets, then a common way of doing this is to create a _variables.scss file. For example:

$primary-foreground-color: white;$body-font-size: 20px;$font-small: 14px;...

Then include the variables in other files: font-size: $body-font-size;

Create your Sass file and add the fonts and layouts. The great thing about Sass is you can load them using partials, so you can have an SCSS file called site, then import all the partials for fonts, variables, layouts and other parts of your web page.

# site.css.scss
@import "fonts/lora";@import "fonts/playfair_display";@import "fonts/open_sans";
@import "variables";
@import 'layout';

Manage layouts and spacing

A simple way to manage page layouts is to add margin or padding to your elements in a stylesheet.

p {    margin: 25px;}

Alternatively you may wish to write your own classes or use one of the frameworks. This post covers Bootstrap, but the principles can easily be applied with other approaches.

Bootstrap has excellent documentation to show you how to use its layout classes and components.

Spacing between headers and paragraphs: Bootstrap has some handy spacing classes to easily add different amounts of padding or margin to elements.

The classes are named using the format {property}{sides}-{size} for xs and {property}{sides}-{breakpoint}-{size} for sm, md, lg, and xl.
- Spacing · Bootstrap

The numbering system goes from 0 to 5, so for example you can add a large margin on the top of a header or paragraph by using the .mt-4 class, which refers to margin top size 4.

h1, h3 {  @extend .mt-4 ;  @extend .mb-2 ;}
h5 {  @extend .my-3 ;}
p {  @extend .mb-4 ;}

For more on @extend and other Sass concepts, check out the Sass Guide.

Setting the maximum width of text body: Unless you really want text to span the entire width of a browser window, creating a div with a class that has a style set to a maximum width can manage this.

.center-content-740px {  max-width: 740px;  margin: 0 auto;}

Add a navbar and user caption

If you want to include these pages within a larger website, then consider styling a layout page that includes a navbar, footer, and possibly some sidebars and social media links.

Then you can include your webpage content or converted markdown files within this layout structure to produce a website with your own Medium-inspired design.

Here is a Codepen with HTML and CSS you can use to get started with your own navbar and user caption → → →

Take it further

See how you can continue to add more of your own personality and brand to your website’s design. Why not try customizing your own social media links, nav bars, fonts choices, layouts, and color schemes? If you like the way that Medium presents its menus, then take a look into popovers and tooltips. Even if you like the idea of your website being inspired by Medium, the ultimate goal is to make it your own.

More from ryanwhocodes