Switching Personal Homepage Theme to al-folio

 2024/01/27 

Since long before have I realized I do need a more official and more academic homepage in addition to a personal blog site, but I didn’t find time to do it until I started working. Now after this switch, I have my personal homepage of al-folio in Jekyll and at the same time my blog of archer in Hexo.

Migrating Hexo Blog to Sub-Directory

I want to keep this archer theme for my blog while creating a new personal homepage. Therefore, I have to move this repo out of the GitHub page repo and into some other blog repo. That is, this blog will now be served as a GitHub project page, like my ARC 40. What needs to be done was surprisingly simple:

Create a GitHub repo to store your webpages: This repo will contain the exact same information as my previous Yao-Lirong/Yao-Lirong.github.io. I created Yao-Lirong/blog.

Change your Hexo _config.yml. You can reference the official guide on deploying, but they didn’t mention how to one-command deploy a project page.

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: https://yao-lirong.github.io/blog
root: /blog/

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: https://github.com/Yao-Lirong/blog
  branch: master
  message: Updated at {{ now('YYYY-MM-DD HH:mm') }}

hexo clean && hexo deploy

Configuring al-folio

Local Install

Since this migration was a long process, when I was working on al-folio, my archer page was still up and I have to first try out al-folio locally to not break my current GitHub page. To do this, the only feasible way is to use docker as suggested in their install instruction. Don’t bother to try other ways. You won’t have any luck running them.

git clone --depth 1 https://github.com/alshedivat/al-folio.git
cd al-folio/
docker compose pull
docker compose up

Personalization

_pages/*.md will be shown on the navigation bar. I deleted most of them and only kept _pages/about.md, cv.md, projects.md
_news/ directory contains what will be shown on the homepage “news” section. Do change those
_sass/_themes.scss has a variable --global-theme-color controlling the theme of this site. I had
1
2
--global-theme-color: #{$cyan-color};
--global-hover-color: #{$light-cyan-color};
In _config.yaml, we see that projects is listed under collections. This means we can build the following file structure, where we have _pages/projects.md to be displayed on the navigation bar as an entry point and projects/p1.md for a specific project. Find more about collections in README
1
2
3
4
5
6
_pages/
├─ projects.md - mywebsite.com/projects/
projects/
├─ p1.md - mywebsite.com/projects/p1
├─ p2.md - mywebsite.com/projects/p2
├─ ....

Integrating Hexo Blog into New Homepage

Delete any blog-related feature that came along with al-folio: reference

Delete all the example posts: rm -rf ./_posts/
Delete the template generating mywebsite.com/blog page: rm -rf ./blog/

Comment out the following entries under Jekyll Archives section and Blog section in _config.yml to make sure absolutely nothing is generated under mywebsite.com/blog address: (I was about to comment out everything, but it turns out this would break some content generation features, so after some experiments I found you only need to comment out the followings:)

# -----------------------------------------------
# Blog
# -----------------------------------------------
permalink: /blog/:year/:title/

related_blog_posts:
  enabled: true
  max_related: 5

# -----------------------------------------------
# Jekyll Archives
# -----------------------------------------------

jekyll-archives:
  enabled: [year, tags, categories] # enables year, tag and category archives (remove if you need to disable one of them).
  layouts:
    year: archive-year
    tag: archive-tag
    category: archive-category
  permalinks:
    year: "/blog/:year/"
    tag: "/blog/tag/:name/"
    category: "/blog/category/:name/"

display_tags: ["formatting", "images", "links", "math", "code"] # these tags will be displayed on the front page of your blog
display_categories: ["blockquotes"] # these categories will be displayed on the front page of your blog

Set the blog entry on the navigation bar link to my actual blog address:

set _config.yml blog_nav_title: to empty, so the al-folio’s blog entry will not show on the navigation bar, reference 1, reference 2

Find in _includes/header.html the if statement {% if site.blog_nav_title %} go to the end of this if statement and add something: reference

{% if site.blog_nav_title %}
<!-- Blog -->
<!-- Empty here because blog_nav_title attribute is empty -->
<li class="nav-item {% if page.url contains 'blog' %}active{% endif %}">
  <a class="nav-link" href="{{ '/blog/' | relative_url }}">{{ site.blog_nav_title }}
    {%- if page.url contains 'blog' -%}
    <span class="sr-only">(current)</span>
    {%- endif -%}
  </a>
</li>
{%- endif %}
<!-- Actual Blog Takes Place Here -->
<li class="nav-item">
  <a class="nav-link" href="https://yao-lirong.github.io/blog/">blog</a>
</li>

One thing really good about al-folio is that it allows including external blog posts. You can do this by adding the RSS feed in _config.yml: reference
1
2
3
external_sources:
- name: blog
rss_url: https://yao-lirong.github.io/blog/atom.xml
These external posts can also be displayed on your homepage if you set latest_posts: true in the front matter of _pages/about.md