Changing blog path in Middleman May 6 2020

I use Middleman as my Static Site Generator, I have two "blogs" in my site:

When I created the TIL blog I wanted it to be my repository of small notes for things I learned that day (hence the name Today I Learned).

Naming is important, and the TIL has prevented me from posting short pieces on my site because it's not something I "learned today". So I decided Notes would be a better name.

And to get started, I'll write a note on how to rename a blog on Middleman.

The parts of the puzzle

We will need to change a few things to make the change.

It goes without saying that if you are using this note as a reference, create a backup of your site before making the changes. I use git for my version control on mostly everything, so I just created a new branch to test these changes. Whatever the method you choose, have some fallback.

Ok, let's begin.

Changing Middleman Configuration

This is my current configuration for the blog (in config.rb):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
activate :blog do |blog|
  # This will add a prefix to all links, template references and source paths
  blog.name = "til"
  blog.prefix = "til"

  blog.permalink = "{title}.html"
  blog.layout = "articles_layout"


  blog.tag_template = "tag.html"
  blog.calendar_template = "calendar.html"

  # Enable pagination
  blog.paginate = true
end

I'll be changing the name and the prefix to notes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
activate :blog do |blog|
  # This will add a prefix to all links, template references and source paths
  blog.name = "notes"
  blog.prefix = "notes"

  blog.permalink = "{title}.html"
  blog.layout = "articles_layout"


  blog.tag_template = "tag.html"
  blog.calendar_template = "calendar.html"

  # Enable pagination
  blog.paginate = true
end

That's step one done. If I try to navigate to the old til URL, I'll see an error. To fix that, we now need to do the change the name of the directory.

Changing the directory name to use the new name

Middleman uses a specific file structure (similar to the following):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
.
├── Gemfile
├── Gemfile.lock
├── build/
│   ├── about/
│   ├── blog/
│   ├── default.html
│   ├── feed.xml
│   ├── images/
│   ├── into_account_contact/
│   ├── javascripts/
│   ├── code/
│   ├── page/
│   ├── privacy/
│   ├── sitemap.xml
│   ├── stylesheets/
│   ├── til/
│   └── til-feed.xml
├── config.rb
├── data/
│   └── sitemap.yml
├── extras/
│   └── rderik_thankfuleyes_theme.rb
├── local.config.yml
└── source/
    ├── _logo.erb
    ├── _menu.erb
    ├── _theme_switch.erb
    ├── about.html.erb
    ├── blog/
    ├── calendar.html.erb
    ├── default.html.erb
    ├── feed.xml.builder
    ├── images/
    ├── into_account_contact.html.erb
    ├── javascripts/
    ├── layouts/
    ├── code.html.erb
    ├── privacy.html.erb
    ├── sitemap.xml.builder
    ├── stylesheets/
    ├── tag.html.erb
    ├── til/
    └── til-feed.xml.builder

Middleman expects to find our "notes" directory inside the source directory, but we still have til so we'll change that. We are going to also rename til-feed.xml.builder to notes-feed.xml.build. That file is in charge of producing the RSS feed for that blog.

1
2
$ mv source/til source/notes                                   
$ mv source/til-feed.xml.builder source/notes-feed.xml.builder

With that out of the way, we can now change the references to til in the posts.

Modifying old the posts

I'll search for til inside source/notes

1
2
3
$ ag "til"
default.html.erb
4:blog: til

Great! Only one result, we only need to change the default.html.erb. I'll make the change, and that's it.

Now we need to modify our source/notes-feed.xml.build. Also the change quite easy just modify the header:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
---
blog: notes
---
xml.instruct!
xml.feed "xmlns" => "http://www.w3.org/2005/Atom" do
  site_url = "https://rderik.com/"
  xml.title "RDerik"
  xml.subtitle "Simplify"
  xml.id URI.join(site_url, blog.options.prefix.to_s)
  xml.link "href" => URI.join(site_url, blog.options.prefix.to_s)
  xml.link "href" => URI.join(site_url, current_page.path), "rel" => "self"
  xml.updated(blog.articles.first.date.to_time.iso8601) unless blog.articles.empty?
  xml.author { xml.name "Derik Ramirez" }

  blog.articles[0..5].each do |article|
    xml.entry do
      xml.title article.title
      xml.link "rel" => "alternate", "href" => URI.join(site_url, article.url)
      xml.id URI.join(site_url, article.url)
      xml.published article.date.to_time.iso8601
      xml.updated File.mtime(article.source_file).iso8601
      xml.author { xml.name "Derik Ramirez" }
      # xml.summary article.summary, "type" => "html"
      xml.content article.body, "type" => "html"
    end
  end
end

Ok with all that changed lest check if everything is working correctly. Visit your local environment before pushing it to the server.

1
$ bundle exec middleman server

I had to update the menu. But aside from that, everything seems to work fine.

Perfect! One last search for til/ to verify everything is working correctly. Found one of my posts pointing to the til/ URL, so I change it. I don't need to make those changes, because we'll add a redirect on .htaccess but if I can make the change directly and don't have to go through the redirect, I'll prefer that.

Now, let's create our .htaccess redirect.

Adding the redirect to our .htaccess

First of all, we are going to generate our .htaccess from Middleman when building.

I'll add a file called htaccess.template.erb on our Middleman source directory. This file is the one that will contain the htaccess information. I'll base my solution on the following tutorial:

https://coderwall.com/p/daflfq/generate-htaccess-in-middleman

So my template will look like this:

1
2
3
4
5
6
7
8
9
10
DirectoryIndex default.html
#Rewrite everything to https
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

# MOVE PERMANENTLY
# Flags: NC=NoCase (Case insensitive), L=Last, no more rules chained
RewriteRule ^til/(.*)$ /notes/$1 [R=301,NC,L]
RewriteRule ^til-feed.xml$ /notes-feed.xml [R=301,NC,L]

And my config.rb will contain the following instructions:

1
2
3
4
page "/htaccess.template", layout:false
after_build do
  File.rename "build/htaccess.template", "build/.htaccess"
end

Now time to test:

1
$ bundle exec middleman build

I check that all my files are ok, and check that the .htaccess exists and has the correct content.

On my side, everything looks good. That's it. I'll deploy it to my server to test it.

Final Thoughts

Great, we managed to change the path for TIL to Notes correctly, and also we are generating the .htaccess file from Middleman. Static site generators are fun and straightforward, it is a fun way to play around with building websites. I hope you enjoyed this small note and find it useful.

If you have any comments or advice, send it my way, it's nice to hear from people that visit the site.

If you like the content, subscribe to the Newsletter, and you'll get a notification when there is a new Article. The Newsletter is the place where I share my thoughts on what I'm exploring and working on, and anything interesting I came across during the week.


** If you want to check what else I'm currently doing be sure to follow me on twitter @rderik or subscribe to the newsletter. If you want to send me a direct message you can send it to derik@rderik.com.