post

Markdown with Code Highlighting Guide

Markdown Post with Code Highlighting Guide

Overview

This guide explains how to create a Markdown-formatted blog post with code highlighting using the Snowlake Jekyll theme and Rouge syntax highlighting.

Front Matter Configuration

Layout and Basic Information

layout: posts/post                # Required layout for post
title: "Post Title"               # Main title of the blog post
date: YYYY-MM-DD HH:MM:SS +TIMEZONE  # Publication date and time

Categorization and Metadata

categories: [category1, category2]  # Post categories
tags: [tag1, tag2]                  # Post tags
author: "Author Name"               # Post author
post_image: "/path/to/featured-image.webp"  # Featured post image

Advanced Metadata

badge_color: "bg-meander"          # Optional badge color
meta_title: "SEO Title"            # SEO-optimized title
meta_description: |                # SEO description
  Detailed description of the post
permalink: "/posts/post-slug"      # Custom permalink

Code Highlighting Techniques

Rouge Syntax Highlighting

{% raw %}{% highlight language %}
  # Your code here
{% endhighlight %}{% endraw %}

Supported Languages

  • Ruby
  • Python
  • JavaScript
  • TypeScript
  • PHP
  • Java
  • C++
  • Go
  • Swift
  • Kotlin
  • And many more!

Code Block Examples

Ruby Code Highlighting

{% raw %}{% highlight ruby %}
def bubble_sort(list)
  return list if list.size <= 1
  swapped = true
  while swapped do
    swapped = false
    0.upto(list.size-2) do |i|
      if list[i] > list[i+1]
        list[i], list[i+1] = list[i+1], list[i]
        swapped = true
      end
    end
  end
  list
end
{% endhighlight %}{% endraw %}

Python Code Highlighting

{% raw %}{% highlight python %}
def fibonacci(n):
    if n <= 1:
        return n
    else:
        return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))
{% endhighlight %}{% endraw %}

Code Formatting Best Practices

Writing Clean Code

  1. Use consistent indentation
  2. Add meaningful comments
  3. Follow language-specific conventions
  4. Keep code blocks concise
  5. Demonstrate practical use cases

Syntax Highlighting Tips

  • Choose appropriate language
  • Use meaningful variable names
  • Highlight key code segments
  • Provide context around code
  • Explain complex logic

Customization Options

  • Customize syntax color scheme
  • Add line numbers
  • Implement code folding
  • Create interactive code blocks
  • Support multiple languages

Performance Optimization

  • Minimize code block size
  • Use efficient syntax highlighting
  • Lazy load code blocks
  • Optimize rendering performance
  • Reduce unnecessary complexity

SEO Considerations

  • Use descriptive code comments
  • Include relevant keywords
  • Provide context for code snippets
  • Use semantic HTML
  • Implement schema.org markup

Accessibility Guidelines

  • Provide code context
  • Support screen readers
  • Ensure color contrast
  • Add ARIA labels
  • Include alternative text explanations

Troubleshooting

  • Verify language syntax
  • Check code block formatting
  • Test across browsers
  • Validate Liquid tags
  • Ensure proper indentation

Example Workflow

  1. Choose a code example
  2. Select appropriate language
  3. Format code consistently
  4. Add explanatory text
  5. Implement syntax highlighting
  6. Review and refine
  7. Publish