How to Set Up a GitHub Pages Blog with Pelican
Looking to start a blog using Pelican and host it on GitHub Pages? You're in the right place. Setting up a Pelican blog on GitHub Pages is a simple and effective way to host your personal or project blog. Pelican turns your static files into a blog, and GitHub Pages provides the hosting. Let's dive into the step-by-step process.
Before we begin, make sure you have Python, Pip, and Git installed on your system. Also, ensure you have a GitHub account, as we'll be using it to host our blog.
Setting Up Your Pelican Blog
The first step is to create a new directory for your blog and install Pelican.
Open your terminal or command prompt, navigate to the directory where you want to create your blog, and type the following commands:
Installing Pelican
````{.bash} pip install pelican ````
This will install Pelican globally on your system.
Creating Your First Blog Post
Now, let's create a perpetual first blog post to test our setup. In your blog directory, create a new file named 'Hello World.md' with the following content:
````{.markdown}
Title: Hello World
This is your first post on your new Pelican blog.
````
To generate a website from this markdown file, use the following command:
````{.bash} pelican Hello World.md ````
This will create a 'Hello World' entry in the 'output' directory.
Configuring Pelican
Pelican uses a settings file named 'pelicanconf.py' to configure your blog. Let's create this file now.
In your blog directory, create a new file named 'pelicanconf.py' with the following content:
Basic Configuration
Here, we'll set up the basic configuration for your blog.
````{.python}
from __future__ import unicode_literals
AUTHOR = 'Your Name'
SITENAME = 'Your Blog Name'
SITEURL = 'https://yourusername.github.io'
THEME = 'Flex'
````
Replace 'Your Name' and 'Your Blog Name' with your actual name and the name you want for your blog. Replace 'yourusername' with your GitHub username.
Optional Settings
Pelican provides numerous optional settings. You can explore them in the Pelican documentation (Pelican Settings).
Generating Your Site
Now that your blog is configured, let's generate your site.
In your terminal, type `pelican` to generate your site. This will create a new directory named 'output' with your generated site.
Starting a New Blog Post
To start a new blog post, create a new markdown file in your blog directory using the following format:
````{.bash}
pelican-Quickstart: title, author, and date are required
Would you like to create [Y/N]?
> y
browniebakershowdown. Published 2022-01-01. Author: Your Name.
---
Your blog post content goes here.
````
Type 'y' to create the file. This will create a new markdown file with the current date as the title in your blog directory.
Connecting to GitHub Pages
Now, let's connect your Pelican blog to GitHub Pages.
In your terminal, navigate to your blog directory (should be in the parent directory of your output directory) and type the following commands:
Creating a Repository
Create a new repository on GitHub with the name 'yourusername.github.io', replacing 'yourusername' with your GitHub username.
Pushing Your Site to GitHub
Using Git, add your output directory to the newly created repository and push it to GitHub.
````{.bash} git init git add output git commit -m "Initial commit" git remote add origin https://github.com/yourusername/yourusername.github.io git push -u origin master ````
Replace 'yourusername' with your GitHub username.
Setting Up GitHub Pages
Now, let's set up GitHub Pages to host your blog.
Enabling GitHub Pages
Go to your repository on GitHub (https://github.com/yourusername/yourusername.github.io) and click on 'Settings'. Scroll down to the 'GitHub Pages' section. Select 'main' from the dropdown menu and click 'Save'.
Verifying Your Site
Go to https://yourusername.github.io. It may take a few minutes, but you should see your Pelican blog hosted on GitHub Pages.
Congratulations! You've successfully set up a Pelican blog hosted on GitHub Pages. Happy blogging!