Styling Markdown with CSS

While Markdown provides semantic structure, CSS allows you to control the visual presentation of your content. Learn how to effectively style your Markdown documents.

Understanding Markdown and CSS

Markdown is converted to HTML, which can then be styled with CSS. The key is understanding:

1. HTML Output: Know what HTML elements your Markdown generates
2. CSS Selectors: Target specific elements effectively
3. Specificity: Understand how CSS rules are applied
4. Responsive Design: Ensure styles work across devices

Basic CSS Integration

Inline Styles

Include CSS directly in your Markdown:

<style>
h1 {
  color: #2c3e50;
  border-bottom: 2px solid #3498db;
}

p {
  line-height: 1.6;
  color: #34495e;
}
</style>

# Styled Heading

This paragraph will use the custom styles above.

External Stylesheets

Link to external CSS files:

<link rel="stylesheet" href="styles.css">

# My Document

Content here will use external styles.

Styling Common Markdown Elements

Headings

/* Primary heading */
h1 {
  font-size: 2.5em;
  font-weight: 700;
  color: #2c3e50;
  margin-top: 0;
  margin-bottom: 0.5em;
  padding-bottom: 0.3em;
  border-bottom: 2px solid #eaecef;
}

/* Secondary heading */
h2 {
  font-size: 2em;
  font-weight: 600;
  color: #34495e;
  margin-top: 1.5em;
  margin-bottom: 0.5em;
  padding-bottom: 0.3em;
  border-bottom: 1px solid #eaecef;
}

/* Tertiary heading */
h3 {
  font-size: 1.5em;
  font-weight: 600;
  color: #34495e;
  margin-top: 1.5em;
  margin-bottom: 0.5em;
}

Paragraphs and Text

p {
  margin-bottom: 1em;
  line-height: 1.7;
  color: #2c3e50;
}

strong {
  font-weight: 700;
  color: #2c3e50;
}

em {
  font-style: italic;
  color: #555;
}

code {
  background-color: #f4f4f4;
  padding: 2px 6px;
  border-radius: 3px;
  font-family: 'Courier New', monospace;
  font-size: 0.9em;
  color: #e74c3c;
}

Links

a {
  color: #3498db;
  text-decoration: none;
  border-bottom: 1px solid transparent;
  transition: all 0.3s ease;
}

a:hover {
  color: #2980b9;
  border-bottom-color: #2980b9;
}

a:visited {
  color: #8e44ad;
}

Lists

ul, ol {
  margin-bottom: 1em;
  padding-left: 2em;
}

li {
  margin-bottom: 0.5em;
  line-height: 1.6;
}

ul ul, ol ol {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

/* Custom bullet points */
ul {
  list-style-type: none;
}

ul li::before {
  content: "▸";
  color: #3498db;
  font-weight: bold;
  display: inline-block;
  width: 1em;
  margin-left: -1em;
}

Code Blocks

pre {
  background-color: #f6f8fa;
  border-radius: 6px;
  padding: 16px;
  overflow-x: auto;
  margin-bottom: 1em;
  border: 1px solid #e1e4e8;
}

pre code {
  background-color: transparent;
  padding: 0;
  font-size: 0.95em;
  line-height: 1.45;
  color: #24292e;
}

Blockquotes

blockquote {
  margin: 1em 0;
  padding: 0.5em 1em;
  border-left: 4px solid #3498db;
  background-color: #f8f9fa;
  color: #555;
  font-style: italic;
}

blockquote p {
  margin: 0.5em 0;
}

blockquote cite {
  display: block;
  text-align: right;
  font-size: 0.9em;
  color: #777;
  margin-top: 0.5em;
}

Tables

table {
  border-collapse: collapse;
  width: 100%;
  margin-bottom: 1em;
  overflow-x: auto;
  display: block;
}

th {
  background-color: #f6f8fa;
  font-weight: 600;
  text-align: left;
  padding: 12px;
  border: 1px solid #dfe2e5;
}

td {
  padding: 12px;
  border: 1px solid #dfe2e5;
}

tr:nth-child(even) {
  background-color: #f6f8fa;
}

tr:hover {
  background-color: #f1f3f5;
}

Images

img {
  max-width: 100%;
  height: auto;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  margin: 1em 0;
}

/* Centered images */
img[alt$="center"] {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

/* Image captions */
img + em {
  display: block;
  text-align: center;
  font-size: 0.9em;
  color: #666;
  margin-top: -0.5em;
  margin-bottom: 1em;
}

Advanced Styling Techniques

Dark Mode Support

/* Light mode (default) */
:root {
  --bg-color: #ffffff;
  --text-color: #2c3e50;
  --heading-color: #1a202c;
  --link-color: #3498db;
  --border-color: #eaecef;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-color: #1a202c;
    --text-color: #e2e8f0;
    --heading-color: #f7fafc;
    --link-color: #63b3ed;
    --border-color: #4a5568;
  }
}

body {
  background-color: var(--bg-color);
  color: var(--text-color);
}

h1, h2, h3 {
  color: var(--heading-color);
  border-bottom-color: var(--border-color);
}

a {
  color: var(--link-color);
}

Responsive Typography

/* Base font size */
html {
  font-size: 16px;
}

/* Tablet */
@media (max-width: 768px) {
  html {
    font-size: 15px;
  }
  
  h1 { font-size: 2em; }
  h2 { font-size: 1.75em; }
}

/* Mobile */
@media (max-width: 480px) {
  html {
    font-size: 14px;
  }
  
  h1 { font-size: 1.75em; }
  h2 { font-size: 1.5em; }
}

Print Styles

@media print {
  /* Remove backgrounds */
  * {
    background: white !important;
    color: black !important;
  }
  
  /* Remove shadows and borders */
  img, pre, blockquote {
    box-shadow: none !important;
    border: 1px solid #ccc !important;
  }
  
  /* Page breaks */
  h1, h2, h3 {
    page-break-after: avoid;
  }
  
  /* Show link URLs */
  a::after {
    content: " (" attr(href) ")";
  }
}

Complete Theme Example

Professional Documentation Theme

/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=Fira+Code&display=swap');

/* Global styles */
* {
  box-sizing: border-box;
}

body {
  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  line-height: 1.6;
  color: #2c3e50;
  max-width: 900px;
  margin: 0 auto;
  padding: 20px;
  background: #ffffff;
}

/* Typography */
h1, h2, h3, h4, h5, h6 {
  font-weight: 700;
  line-height: 1.25;
  margin-top: 1.5em;
  margin-bottom: 0.5em;
}

h1 {
  font-size: 2.5em;
  color: #1a202c;
  border-bottom: 3px solid #3498db;
  padding-bottom: 0.3em;
}

h2 {
  font-size: 2em;
  color: #2d3748;
  border-bottom: 2px solid #e2e8f0;
  padding-bottom: 0.3em;
}

/* Code */
code, pre {
  font-family: 'Fira Code', 'Courier New', monospace;
}

code {
  background-color: #f7fafc;
  color: #e74c3c;
  padding: 0.2em 0.4em;
  border-radius: 3px;
  font-size: 0.9em;
}

pre {
  background-color: #2d3748;
  color: #e2e8f0;
  padding: 1.5em;
  border-radius: 8px;
  overflow-x: auto;
  line-height: 1.5;
}

pre code {
  background: transparent;
  color: inherit;
  padding: 0;
}

/* Links */
a {
  color: #3498db;
  text-decoration: none;
  transition: color 0.2s ease;
}

a:hover {
  color: #2980b9;
  text-decoration: underline;
}

/* Tables */
table {
  border-collapse: collapse;
  width: 100%;
  margin: 1.5em 0;
}

th, td {
  padding: 12px 15px;
  text-align: left;
  border: 1px solid #e2e8f0;
}

th {
  background-color: #f7fafc;
  font-weight: 600;
  color: #2d3748;
}

tr:hover {
  background-color: #f7fafc;
}

/* Blockquotes */
blockquote {
  margin: 1.5em 0;
  padding: 0.5em 1.5em;
  border-left: 4px solid #3498db;
  background-color: #f7fafc;
  font-style: italic;
}

/* Task lists */
input[type="checkbox"] {
  margin-right: 0.5em;
}

CSS Frameworks and Markdown

Using Tailwind CSS

<div class="prose lg:prose-xl">

# My Document

This content will use Tailwind's typography plugin styles.

</div>

Using Bootstrap

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">

<div class="container">
  <div class="row">
    <div class="col-md-8">
      
# Main Content

    </div>
  </div>
</div>

Best Practices

1. Use CSS Variables: Make themes easily customizable
2. Mobile First: Design for mobile, then enhance for larger screens
3. Accessibility: Ensure sufficient color contrast and readable fonts
4. Performance: Minimize CSS, remove unused rules
5. Consistency: Use a consistent spacing and typography scale

Tools and Resources

• CSS Validators: Check your CSS for errors
• Autoprefixer: Add vendor prefixes automatically
• PurgeCSS: Remove unused CSS
• PostCSS: Transform CSS with JavaScript plugins

Conclusion

CSS gives you complete control over how your Markdown content appears. Combine semantic Markdown with thoughtful CSS to create beautiful, accessible documents.

Additional Resources

• MDN CSS Guide
• CSS-Tricks
• Can I Use
• A Complete Guide to Flexbox