Published: Sun 25 March 2018
Updated: Sun 25 March 2018
pelican publishing blog How I set up Pelican to work with a custom domain on Github
I have successfully set up Pelican to use with Github, as well as placing the CNAME correctly. There will be a list of links at the bottom for all the sources I used to get me to here.
My set up is on a Win10 box but amazingly I didn't have to do too much to get Pelican up and running.
Step One - Get Pelican Installed
Here I'm going to tell you to pretty much follow what Rasor (2 below) did with a few modifications. I'm going to assume that you have already gone onto Github and created a user page like
username.github.io. I will show you how to then create a CNAME if you have a custom domain. For set up within github I'll direct you to link 3 below.
pip install pelican markdown
pip install ghp-import
First pip is just to get pelican and markdown. Unless, you want to use something other than markdown. Check the documentation of Pelican for that.
Now since you have created your repository pull it down.
git clone git@github:*username*.github.io.git
Change into the directory of you repository. And issue the checkout command:
We are doing this so that all of the source work is saved separately from the content that will be displayed. Per github all content we want to keep in the master branch. You will need to remind yourself of the workflow.
- source branch: pelican
- content branch: master
Go ahead and fetch
.gitignore file from https://github.com/getpelican/pelican-blog/blob/master/.gitignore save it to the root of the repository.
And create a README.md also at the root. If you already created one when you created your personal page then it should already be there.
Step Two - Quickstart Pelican
Pretty much all you do here is the same as the docs: http://docs.getpelican.com/en/stable/quickstart.html.
Run the following in your repository:
Answer all the questions especially these two:
- Do you want to specify URL prefix? Answer https://
- Do you want to upload using xxx? Answer N untill the xxx = GitHub Pages
Once you are done you will have pelican set up with the project workflow. All content will be kept in the content folder and all output, for local use will be kept it output. You will send the output folder to master when you are ready to publish to github.
And now per Rasor it's time to add content. Here you can use markdown or Restructured Text. I use markdown so all the files will end with the md extension. Check out the docs about how to struture your content file. It requires the use of tags. Here is a sample from the docs:
Title : My super title
Date : 2010 - 12 - 03 10 : 20
Modified : 2010 - 12 - 05 19 : 30
Category : Python
Tags : pelican , publishing
Slug : my - super - post
Authors : Alexis Metaireau , Conan Doyle
Summary : Short version for index and feeds
This is the content of my super blog post .
Step Three - Check it out!
So, you have the first items set up and a blog post created and sitting in the content folder. To view it without publishing it:
Now, you can either run the pelican server:
python -m pelican.server
Or just open the index.html file with your browser. It is a static website so everything will be clickable so long as the html links, or images are correct. Check the documentation for formatting those items.
Once everything looks good it's time for...
Step Four - Custom Domain(skip if you are not doing this)
Okay, for a custom domain I'll assume that you already have everything set up with the web registrar. They usually can supply you with everything but you want pelican to put that out there on github for you so it'll be processed by them and you can then use your domain for your personal github page.
Create a folder under content:
And create a CNAME file in extra and place your domain name in that file. Now, just save it.
Github and your domain registrar has all the information for making sure that domain points to your github account so look up those instructions.
Step Five - Publish to git
First the Source
Run the following to add the source to your pelican branch:
git add .
git commit -a -m 'Initial Commit'
git push origin pelican
Remember: you will need to do this for each new blog post added to content but I'm not sure you would have to. But it is a good way of keeping all the original source material in sync with github. This way if you lose the local content you have a back up.
Now the content
Now run the following to generate new pages, and output to master for publishing:
pelican content - o output - s pelicanconf . py
ghp - import output - r origin - b master
git push origin master
And that is it. The biggest this to remember is when creating a new blog post it to make sure you are saving it in the pelican branch of content.
I'll include hooking up comments to my blog once I've checked otherwise feel free to send me an email. You can find me email address down below.
2. Rasor's Tech Blog
3. Github Pages - Custom Domain
4. Pelican - Tips Page for CNAME