DEV Community: Christian

Integrating a Blog section to your Rails app using Markdown in minutes

Christian — Sat, 27 Jan 2024 09:57:05 +0000

Having a blog on your website is a fantastic way to attract new visitors and ensure search engines, like Google, index your content. I recently faced this challenge while working on my web app, tiTrovo.casa, a free service assisting users in finding homes to rent or buy in Italy.

Recognizing the value of sharing experiences, especially when dealing with complex topics like Italian bureaucracy, I decided to add a blog section. People often seek practical advice from those who've been through similar situations, and having personally navigated the intricacies of the Italian system, I knew a blog could be immensely helpful.

Defining Our Objectives

The idea is to create articles quickly using Markdown, a user-friendly and familiar format. These Markdown files will collectively form the article list within the blog section.

A functional blog section should have an index page listing all available articles, each with its title, description, images, and additional information. Clicking on an article should smoothly transition the user to the dedicated article page, styled with our custom CSS. For a modern touch, we might even consider adding share buttons at the end.

Tools of the Trade

So, how do we achieve all of this using just Markdown files?

Here's our roadmap:

Parse Markdown files and convert them to HTML.
Make Rails dynamically recognize routes.
Extract information from Markdown files: title, description, image, and article URL.
Customizing the article page.

Let's dive into step 1.

Parsing Markdown Files and Converting to HTML

To accomplish this, we'll leverage the Redcarpet gem, a straightforward tool for Markdown conversion.
Following the gem's README, we can use the following code snippet:



markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, extensions)
markdown.render("This is *markdown*, indeed.")

This converts Markdown to HTML, and we can further customize the HTML generation with extensions if needed. For this tutorial, we'll keep it simple.

To automate the processing of .md files with Redcarpet in a Rails application, let's create our MarkdownToHtml:



# lib/converters/markdown_to_html.rb

module Converters
  class MarkdownToHtml
    def call(template, source)
      markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML)

      "#{markdown.render(source).inspect}.html_safe"
    end
  end
end

Next, create an initializer to bind the Markdown converter to files with the .md extension:



# config/initializers/converters.rb

require 'converters/markdown_to_html'

ActionView::Template.register_template_handler(:md, Converters::MarkdownToHtml.new)

With these configurations, Rails is ready to process Markdown files placed in the app/views/blog/ folder.

To view it in your browser, add the required route:



# config/routes.rb

get 'blog/my_first_article', to: 'blog#my_first_article'

And create the Rails controller, BlogController in this case:



# app/controllers/blog_controller.rb

def my_first_article; end

At this point, creating the app/views/blog/my_first_article.md file should display its content in the browser. 😁

2. Making Rails Recognize Dynamic Routes

Instead of manually adding a new route and action for each article, let's make the routes dynamic.

Open the routes file and add two routes: the index and the article "show" page:



# config/routes.rb

get 'blog', to: 'blog#index'
get 'blog/:any', to: 'blog#article'

Now, create the article action in the BlogController:



# app/controllers/blog_controller.rb

def index; end

def article
  render params[:any].to_sym
end

Magic! This setup renders the right article based on the params[:any] provided in the URL.

For now, the index action is empty, but we'll fill it in the next step.

3. Extracting Information from the Markdown File

To collect article information, we'll utilize front matter!

What is front matter?

In the world of Markdown, front matter is a powerful tool that allows you to embed metadata or configuration settings directly within your document. This metadata is typically placed at the beginning of a Markdown file and is enclosed by triple dashes (---).



---
title: My Awesome Blog Post
author: John Doe
date: 2024-01-25
tags:
  - Markdown
  - Front Matter
  - Blogging
---

# Heading 1

This is the content of my blog post. Front matter provides a convenient way to include additional information about the document, such as the title, author, date, and tags.

In this example, the front matter contains metadata such as the title of the blog post, the author's name, the publication date, and a list of tags associated with the content. This structured information can be leveraged by various systems and tools to enhance the presentation and organization of your Markdown documents.

Front matter is commonly used in static site generators, blogging platforms, and other applications that process Markdown files to provide a richer and more customizable user experience.

Integrating front matter

At the beginning of each Markdown file, include front matter with blog post information you want to display in the posts list. Common fields include:



---
title: Article title
image: "/blog/article_image.png"
description: description
# other information here
---

Parse these front matter fields using the front_matter_parser Ruby gem, like this:



content = File.read('article.md')
parsed = FrontMatterParser::Parser.new(:md).call(content)

parsed.front_matter # contains title, image, description and other fields

and integrate this into our BlogController:



  def index
    blog_folder = 'app/views/blog'

    # Array<{ title:, description:, image:, url: }>
    @articles = Dir.new(blog_folder)
                   .children
                   .select { _1.ends_with?('md') }
                   .map do |filename|
                     fm = FrontMatterParser::Parser.parse_file("#{blog_folder}/#{filename}").front_matter
                     fm.merge!(url: "blog/#{filename.gsub('.md', '')}")
                     fm.with_indifferent_access
                   end
  end

We've added the url for each blog post since we dynamically calculate the equivalent of the show page, allowing users to navigate to that page when clicking on a blog post.

4. Customizing for the article page.

With our fully functional blog section showcasing a list of available posts and the ability to navigate to individual post pages, let's add the finishing touches for a polished user experience. In this step, we'll focus on customizing the article page by introducing custom CSS styling and incorporating a social sharing feature using AddToAny.

Here's how we make these enhancements to the MarkdownToHtml:



module Converters
  class MarkdownToHtml
    TEMPLATE_CONTENT = <<-HTML
      <div class="post-page">

        ${content}

        <!-- AddToAny BEGIN -->
        <div class="a2a_kit a2a_kit_size_32 a2a_default_style">
          Condividi su
          <a class="a2a_button_x"></a>
          <a class="a2a_button_whatsapp"></a>
          <a class="a2a_button_facebook"></a>
          <a class="a2a_button_telegram"></a>
          <a class="a2a_button_linkedin"></a>
        </div>
        <script>
            var a2a_config = a2a_config || {};
            a2a_config.num_services = 5;
        </script>
        <script async src="https://static.addtoany.com/menu/page.js"></script>
          <!-- AddToAny END -->
        </div>
      </div>
    HTML

    def call(template, source)
      markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML)

      # remove the front matter information
      sanitized_source = source.gsub(/---([\S\s]*)---/, "").strip

      html = TEMPLATE_CONTENT.gsub("${content}", markdown.render(sanitized_source))

      "#{html.inspect}.html_safe"
    end
  end
end

In this modification, we've introduced the ${content} placeholder in the HTML template, acting as a marker for the Markdown content. This placeholder gets replaced with the actual HTML-rendered content using the gsub method.

Additionally, we've removed the front matter information from the source to prevent it from appearing in the final HTML.

To make the page visually appealing, create a CSS file, for example, app/assets/stylesheets/blog.scss, and define styles for elements inside .post-page:



.post-page {
  margin: auto;
  padding-top: 2em;

  @media (min-width: $mobile-width) {
    max-width: 800px;
  }

  h1 {
    font-size: 2em;
    text-align: center;
    margin-top: 0.8em;
    margin-bottom: 0.8em;
  }

  h2 {
    font-size: 1.6em;
    margin-top: 2em;
    margin-bottom: 0.7em;
  }

  p {
    line-height: 2;
    font-size: 19px;
  }

  img {
    aspect-ratio: 5/3;
    object-fit: cover;
    height: 100%;
    border-radius: 8px;
    margin-top: 0.8em;
  }

  .a2a_kit {
    display: flex;
    justify-content: flex-end;
    margin-bottom: 3rem;
    margin-top: 3rem;

    a {
      margin: 0 0.3rem;
    }
  }
}

This CSS file defines styles for various elements within .post-page, ensuring a visually pleasing layout for your blog posts.

Feel free to customize these styles further to match your design preferences. As your blog takes shape, these enhancements will contribute to a delightful reading experience.

Conclusion

In conclusion, with this step-by-step guide, you've empowered your Rails application with a dynamic and Markdown-driven blog section. By seamlessly integrating Redcarpet for Markdown conversion, creating dynamic routes, and utilizing front matter for rich metadata, you've crafted an engaging space for sharing valuable content.

Now, as your blog section takes shape, remember that this is just the beginning. Explore further customization, experiment with styling, and continue sharing your insights. Whether you're a seasoned developer or just starting, the versatility of Markdown brings a user-friendly approach to content creation.

Feel the satisfaction of providing practical advice, sharing experiences, and connecting with your audience.

If you have questions, feedback, or encounter any challenges along the way, don't hesitate to reach out on Twitter. Happy blogging!

Rails live reloading assets

Christian — Thu, 02 Jun 2022 14:58:12 +0000

Recently I've been trying to learn more about the Rails assets pipeline. The standard documentation is very well written and has tons of tips and best practices but there's something I was still missing: live reloading the assets, in particular the css/scss assets.

Working with React this is the pretty standard behaviour: you update a file and you can instantly see the changes on the browser.

The Rails documentation does not explain how to obtain this behaviour and, honestly, I've never managed to make the live compilation work, so I've been killing the server, running bundle exec rails assets:precompile and restarting the server the whole time, until now.

Luckily, a few days ago I discovered an handy gem that solves this issue in a very simple way: rails_live_reload.

Install the rails_live_reload

Adds this gem in the development group, or whatever group you need, in you Gemfile



group :development do
  gem 'rails_live_reload'
  ...
end

and un bundle install.

Tweak the development settings

Open the config/environments/development.rb file and add these lines:



config.assets.compile = true
config.assets.digest = false

the assets.compile option enables the live compilation through Sprockets, as stated in the official documentation while the assets.digest turns off the generation of digest strings for the assets names. To be honest I'm not sure why the latter is required but if it is omitted both the live reloading and the live compilation won't work.

Run the css watch

We need to open a terminal window and spawn the process that watches for changes in the the css/scss files.
If you are using the dartsass-rails gem you can run:



bundle exec rails dartsass:watch

while if you are using cssbunding-rails or any other solutions you probably want to run:



yarn build:css --watch

keep this terminal running, do not kill it.

The Rails server

Finally, open a new terminal and run the Rails server to enjoy the live reloading assets 😎.

Feel free to write any suggestion or question in the comments. I would be really happy if someone could explain to me, and everyone who will read this tutorial, why the config.assets.digest = false is required to make the auto compilation/reloading work 🤯

How to install the mysql2 Ruby gem on a Mac M1

Christian — Wed, 18 May 2022 07:27:27 +0000

The Mac M1 family has been presented more than two year ago and I still encounter a new issue every time I try to install the mysql2 Ruby gem.
But... I think I've finally found a set of commands to fix all these issues!

First of all, install the required dependencies:

brew install gcc zstd openssl mysql

now export all the libraries paths which we need to build the gem:

export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl@3/include"
export LIBRARY_PATH=$LIBRARY_PATH:$(brew --prefix zstd)/lib/

aaaand now install the mysql gem:

gem install mysql2 -v '0.5.4' -- --with-opt-dir=$(brew --prefix openssl) --with-ldflags=-L$(brew --prefix zstd)

woila', I'm 100% this will succed, if don't please leave a comment so we can figure out a new solution to help who will read this post 🚀

Small tip to reduce your Docker images size

Christian — Thu, 05 May 2022 12:59:12 +0000

Hi everyone, first post on dev.to, I whish to be more active in the future!

Today I want to explain a small tip I recently fond out to reduce the Docker images size, in my case I was able to reduce the size by half!

Let's assume that you are working with a language like Ruby or Python, even if these languages are not compiled they often need some system libraries to work properly, in particular if you are working with databases (MySQL, SQLite, Postgres) you need to compile the gem or the library for the specific architecture of your machine.

In my case I'm working with Ruby and I'm trying to install the SQLite gem that, unfortunately, requires the build-base system library.

Here is the project I'm working on:
Faenz Analytics

So I thought to install it, compile the SQLite gem and uninstall everything I do not need anymore, here is my Dockerfile:

FROM ruby:3.0.4-alpine3.15
WORKDIR /faenz-analytics
RUN apk update && \
    apk add make && \
    apk add build-base && \ # this takes 200Mb of space!!
    apk add sqlite-dev

# ...some instructions

RUN bundle install  # installing Ruby gems
RUN apk del build-base

# ...some other instructions

easy, right? we installed build-base, compiled and installed the gems and removed build-base to reduce the image size.

The problem is that this does not work! The image size is the same as if we did not remove build-base. Let's discover why.

We wrote three RUN instructions, each one generates a layer and these layer are put togheter by Docker to create the final image:

the first RUN installs the system libraries
the second RUN install the gems/libraries by Ruby or whatever language you are using
the third RUN removes the system libraries

since we installed the system libraries in one of the layer they will take some space and will increase the image size, there's no way we can reduce the image size with the next layers.

It's like a sum with no negative numbers. The size can only increase or stay the same from a layer to another.

What? Don't give up, we got this 🚀

Here is the solution: put these operations in the same layer!

FROM ruby:3.0.4-alpine3.15
WORKDIR /faenz-analytics
RUN apk update && \
    apk add make && \
    apk add sqlite-dev

# ...some instructions

RUN apk add build-base && \
    bundle install && \
    apk del build-base

# ...some other instructions

grouping the operations in just one RUN instruction avoids Docker to waste space to store the build-base in a layer. The layer is generated at the end of the instruction so we are going to install, use the build-base and prontly remove it so that the layer will not contain it at all.

With this little tip my image size went from 400Mb to 170mb, less than half!

If you want to exagerate with the micro optimizations, you can apply the same solution to apk update (or apt-get update for debian/ubuntu images) by deleting the cache created by this command:

RUN apk update && \
    add build-base && \
    # install other dependencies here...
    bundle install && \
    apk del build-base && \
    rm -rf /var/cache/apk && \
    rm -rf tmp/cache

I'm not a Docker expert, so, if you know a better solution or want to share similar tips to reduce the image size please leave a comment, I'm all ears 🙏