DEV Community: Bassel Cheaib

Add a portfolio to your Ghost blog

Bassel Cheaib — Sat, 12 Dec 2020 10:41:32 +0000

When building a personal blog, you don't have to re-invent the wheel and implement everything from scratch. Many people tend to use a CMS in order to focus more on the blog's content instead of having to focus on building the barebones of the blog (taxonomies, pagination, SEO, etc) from scratch.

There are many solutions available like WordPress, Drupal, Ghost, etc. Each one has its own pros and cons, but for me I've always been a fan of Ghost when it comes to managing blog content.

One special thing about Ghost is that it focuses mainly on content publishing. But does that mean that it can't be used for other types of content? Not at all. Thanks to its flexible routing system, it allows you to also build powerful custom site structures.

Here's how you can customize the default routes to add your personal portfolio to a ghost blog.

Understanding collections and channels

In ghost, you can create your own specific channels in order to change the organization of your content and what URLs they live on. It's important to note that a post can be only in one collection. That's why it's necessary to properly setup your filters to insure that.

But what if you want a post to be accessible from multiple routes? Like for example when you want a project to be displayed on your general portfolio and on a page where you only have mobile projects? Well, that's where channels come to the rescue. A channel is a collection of content matching a specific filter. Unlike collections, they don't influence the post's URL which is why it's possible to have a post present on multiple channels.

Enough theory for now... Once we see an example in action, you'll have a better idea about the difference between collections and channels.

Adding the portfolio projects

The first thing to do is to create a tag called "Portfolio" (the name doesn't really matter, so you can choose any other name you want). This will be the primary tag assigned to all of our portfolio projects. Just like with any other post, you can assign as many tags to the project. The important thing is to have the same primary tag for all the projects you add (It's the Portfolio tag in this case).

A project is just like any other post, except that it has the tag Portfolio:

Once you add a couple of projects, you'll notice that they will appear on your home page alongside the other posts. But ideally, we'd want our portfolio to be separate from the blog.

Separating the portfolio from the blog

The first step now is to download your routes file. To do that, go to the Labs section in your dashboard and press on "Download current routes.yaml" at the very bottom.

By default, your routes.yaml should look like that:

routes:

collections:
  /:
    permalink: /{slug}/
    template: index

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

What we need to do now is to filter out the portfolio items from the home page and move them to their own directory. In addition to that, we'll use the template page of the tag in order to display a header and a small description about the portfolio. The updated routes.yaml looks like this:

routes:

collections:
  /:
    permalink: /{slug}/
    filter: primary_tag:-portfolio
    template: index
  /portfolio/:
    permalink: /portfolio/{slug}/
    filter: primary_tag:portfolio
    template: tag
    data: tag.portfolio

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

So what happened here?

The filter property under home is telling it to get all the posts except the ones that have a primary tag of portfolio (notice the minus sign before portfolio)
The filter under /portfolio/ tells it to get only the ones with the primary tag of portfolio.

By using these two filters, we ensure that anything with portfolio as a primary tag will belong only to the portfolio collection. A few more thing to note:

The permalink of the portfolio collection is /portfolio/{slug}/ which means that all the posts that belong to this collection will have a URL of this form
The template we're using is tag which tells the theme to use the tag.hbs template when building the portfolio page. You can even create a custom template and use it for your portfolio page by specifying it here.
Since the tag template needs the data of a tag to display properly, we are passing the portfolio tag's data by specifying the data property of the collection.

Using channels to create specialized profiles

Let's say you want to show someone all the mobile apps you built previously by sending them the link portfolio/mobile/. You could follow the same process as before and create that as a collection, but as we mentioned before a post can live in one collection only. Which means that by doing this, they won't appear in your primary portfolio page anymore.

In cases like that, it's better to use channels. You can think of channels as a set of permanent search results. It allows you to have a filtered slice of content from your site, without modifying the content itself.

Here's an example of how you can do that inside your routes.yaml:

routes:
  /portfolio/mobile/:
    controller: channel
    filter: tag:portfolio+tag:mobile
  /portfolio/desktop/:
    controller: channel
    filter: tag:portfolio+tag:desktop
  /portfolio/web/:
    controller: channel
    filter: tag:portfolio+tag:websites

collections:
  /:
    permalink: /{slug}/
    filter: primary_tag:-portfolio
    template: index
  /portfolio/:
    permalink: /portfolio/{slug}/
    filter: primary_tag:portfolio
    template: tag
    data: tag.portfolio

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

All the new modifications are inside routes. What happens now is that all the posts matching the specific filter you set on a certain route will appear inside that route while still appearing inside their own collection too.

There are tons of filters you can use; here's an example of the possible combinations you can have:

filter: tag:x+tag:y # must have both "x" and "y" tags (+ = AND)
filter: tag:x,tag:y # can have either "x" or "y" tags (, = OR)
filter: tag:-x+tag:y # must have tag "y" but not tag "x" (- = NOT)
filter: tag:[x,y,z] # must have either "x", "y", or "z" tags ([] = IN)
filter: tag:-[x,y,z] # must not have any one of "x", "y", or "z" tags (-[] = NOT IN)
filter: author:steve+tag:x # must be written by "steve" and have tag "x"

Setting the new routes.yaml

By now, we have our updated routes.yaml, and all we need to do is set it on our website. To do that, you go to the lab section on the dashboard and you go to the same place where you downloaded the initial file. From there, you can press the Upload routes YAML button and select the updated file to upload.

Adding redirects

One more thing you can do is to set a redirect from /tag/portfolio to portfolio directly because they are now the exact same page (same layout, data and content). To do that, download your initial redirects file from the lab. If you haven't worked with it before, it should be an empty file.

Now add the redirect you want to it. In our case it becomes:

[
  {
    "from": "/tag/portfolio/",
    "to":"/portfolio/",
    "permanent":true
  }
]

Then re-upload it like you did for the routes.yaml file.

That's all! Thank you for reading and have a nice day!

Hosting your Ghost blog on GitHub pages for free

Bassel Cheaib — Sat, 12 Dec 2020 10:28:59 +0000

GitHub Pages is an amazing solution for hosting static websites. By using static site generators (like Jekyll, Hugo, Gatsby and many others) you can easily host your personal blog for free there.

But what if you're using a CMS like Ghost to manage your blog? Does that mean that you'll end up having to pay in order to host it?

Well, not necessarily. You can have a local installation of Ghost where you manage everything, then convert it to a static site and publish it for free every time you make changes! Let's get into more details regarding how to do that.

Assumptions

Before you continue with this article, you'll need to complete the following:

Have a running local installation of ghost on your machine. You can do that by following this guide.
If you're a Windows user, you'll need to have the Windows Subsystem for Linux enabled. Here's how you can do it.

Generating the static site

In order to generate the static site, we'll use the Ghost static site generator. With Linux and macOS, this tool can be used directly. However, it's more challenging when you're running on a Windows machine.

The reason for that is that this tool uses wget and grep under the hood. That's where the Windows subsystem for Linux comes to the rescue. If you're not using a windows machine, you can directly skip to step 2.

1. Prepare the environment (Windows only)

Launch the Linux shell and make sure to install npm inside it. To do that, you can run the following command:

sudo apt update && sudo apt install npm

2. Install the tool globally

You can do that by running:

sudo npm install -g ghost-static-site-generator

For windows users, you can now exit the Linux shell by running the exit command.

3. Generate the site

Create an empty directory of your choice
Open a terminal in this directory (Windows: press SHIFT + Right Click inside this directory then select "Open Linux shell here")
Make sure your local ghost installation is running and accessible through the browser. By default it should be running on localhost with the port 2368
Run the following command:

gssg --url https://username.github.io

This assumes you'll be pushing the code to your main GitHub site repository named username.github.io, where username is your username (or organization name) on GitHub.

In case you were using a custom URL or even publishing it to other providers like Netlify, change the URL accordingly. The important thing is that it matches the URL where the site will be deployed.

4. Deploy it online

By now, you should have a folder named static inside the folder you created earlier. This is where the entire static website has been generated. All you have to do is push this code to the repository and wait for it to be deployed.

Bonus: if you're using Netlify, you can also just drag and drop this folder into the sites section on your dashboard and it will be automatically deployed.

That's all! Whenever you create new content or update anything, all you need to do is repeat steps 3 and 4.

Small note: There's another possible approach that allows you to make this process even simpler, which is to use Ghost as a headless CMS for a static site generator (Gatsby, Hugo, Next.js, etc). If you'd like to know more about that, you can check the following links: