This site was made using the Pelican static site generator, and hosted on Github pages

It took a fair amount of trial-and-error to get this site live, so I thought I would post my process here for future reference, and in case it helps anyone else out. Please note these are just the steps that I took to get the site going, and not necessarily the best or most optimal steps. They are just what worked for me.

Initialize the site directory

1. Choose a directory for the site to live in. For me, it was /home/sbh/Documents/Code/Website

2. Open the directory in a text editor, which for me is Visual Studio Code. Initialize a new python virtual environment for the directory.

3. In the terminal, enter pip install pelican markdown.

4. Then, enter pelican-quickstart in the terminal. This will create a folder structure along with a few files for pelican within the directory. These will be discussed below, but for now there are a couple more steps before the bare bones of the site is ready to publish.

5. Create a sample article by creating a new Markdown file in the content folder. I used the sample file suggested in the official documentation. Make sure you save this file (ctrl+S).

   Title: My First Review

   Date: 2010-12-03 10:20

   Category: Review

   Following is a review of my favorite mechanical keyboard.

6. With pelican, any Markdown articles or pages posted to the content folder will be converted to html. In order to perform this process, run the command pelican content in the terminal. After doing so, you should see the test article appear as an html file in a new folder called output. This output folder contains the actual pages of the site.

7. Lastly, to preview the site, run the command pelican --listen and click the link to view the site locally. Hit ctrl+C in the terminal to stop serving the site locally.

The pelican folder structure

After completing step 4, the following folders will be present in the Website directory: * .venv/ - Contains the virtual environment

• content/ - Add files to this folder to add pages and posts to the site

• output/ - Do not edit this folde; it will be deleted and recreated every time you run pelican content

• pelicanconf.py - You can change several settings in this file in order to affect the website

• publishconf.py - This will rarely need to be changed

• tasks.py - This should not need to be changed

Create repository and push repo to Github

Now that the bones of the site are creative, you need to create a remote repository in order to host the site on Github Pages. 1. On github.com, create a new repository with using github_username.github.io as format for the repository name.

1. In the text editor, install the GitPython library by entering pip install gitpython into the terminal.

2. Create a git repository within the Website directory by entering git init into the terminal.

3. To create a remote repository (sync your local repository with the one created on github.com), enter git remote add origin https://github.com/github_username/github_username.github.io into the terminal.

4. Each time you want to push a change to your website and make it live online, you will need to commit a new change the repository. This first step of doing this is to enter git add ./output into the terminal. To see what files you've staged to commit, you can enter git status.

5. To actually commit your changes, enter git commit -m 'your commit message'. For example, I entered git commit -m 'Added Making Of Site article'.

6. Lastly, once you've committed a change to the repository, you will need to push the change to your remote repository using git push. After this, you should be able to see your output files in your github.com repository.

Make site live with Github Pages

Now that the site's files are successfully uploaded to github.com, the last step is to host them on github pages. Admittedly this was very tricky for me and I used a lot of trial and error.

1. In the Website directory, create a text file titled .nojekyll. Add this to the local repo, commit the change, and then use git push to push it to the remote repo. I'm not sure how effective this step is. I know Github Pages uses Jekyll by default and I'm not sure if that interferes with Pelican. It's a step I saw many people take as I was researching how to build the site, so it's one I took as well.

2. On github.com, and on the remote repository, go to the settings page, and then the pages section. Deploy the site using Github Actions, selecting Deploy static content to Pages as the action. Use the output folder as the source. If this is successful, you shuld be able to go to https://github_username.github.io and view your site!

Adding a custom domain

1. To add a custom domain, list the domain in the box on the Pages section of the repository settings. This should create a new CNAME file in your remote repository. Don't delete this file!

2. On the site where you purchased your domain name, add the following records:

   Type	Host	Value
   A Record	@	185.199.108.153
   A Record	@	185.199.109.153
   A Record	@	185.199.110.153
   A Record	@	185.199.111.153
   CNAME Record	www	github_username.github.io

3. Return to the Github Pages settings and refresh. Wait for the "DNS Check In Progress" to complete successfully, and then check the Enforce HTTPS.

Conclusion

Though it was a frustrating process to work through at times during the initial setup, at the end of the day, using Pelican with Github pages is a really simple way to make a striking static site. Once the inital setup is complete, adding new content is as simple as the following steps. There is another important layer that involves changing and customizing the page's theme, but that's a story for another post, I think, as I am still figuring that part out.

To add new content

1. Create a new Markdown file in the content directory.
2. Do pelican content to generate the new files for the output directory.
3. Do pelican --listen to preview the site locally, and Ctrl+C to stop.
4. Use git add ./output.
5. Use git commit -m "Commit message"
6. Do git push to upload to github.com, and after a few minutes your new content should be available at the URL of your github repo, or your custom domain.