Additionally, you can avoid vendor lock-in associated with using something like Wordpress as all your content will be in simple marked up text files maintained both locally and on GitHub.
I'll leave the first three to you.
Before continuing I first must acknowledge this walkthrough from Fedora Magazine. Mine is similar but with a few additions and instructions which should work on any OS.
You can install Pelican with pip or your package manager on some Linux distribution.
On Ubuntu try:
sudo apt-get install python-pelican
With pip (in Windows, for example):
pip install pelican
Restart your shell so you can use pelican utility commands. There's a lot more info on their docs site so if you have challenges head there.
GitHub Pages init
To create a GitHub pages site you need to at least create a new repository named you.github.io (where you is substituted by your GitHub user name). To support the Pelican project workflow we will create two:
- you.github.io-src will contain the Pelican project used to generate the static website
- you.github.io will contain the website itself output from a Pelican project
Create these repositories on GitHub, being sure to initialize with a README to facilitate cloning locally.
Clone the source repo into a ghpages directory.
git clone https://www.github.com/you/you.github.io-src ghpages; cd ghpages
Add the website repository as a git submodule in the project's output directory.
git submodule add https://www.github.com/you/you.github.io output
Starting the Pelican Site Project
You can easily get started with the pelican quickstart utility:
cd /path/to/ghpages pelican-quickstart
There will be several prompts, use similar answers to the following. Note I am not using either Fabfile or Makefile for automation. These are more useful if publishing to a personally managed server (i.e. not GitHub).
- Where do you want to create your new web site? [.]
- Do you want to specify a URL prefix? e.g., http:example.com Y
- What is your URL prefix? (see above example; no trailing slash) http://you.github.io
- Do you want to generate a Fabfile/Makefile to automate generation and publishing? N
- Do you want an auto-reload & simpleHTTP script to assist with theme and site development? N
- Do you want to upload your website using ...? Y for only GitHub Pages
- Is this your personal page (username.github.io)? Y
Ignore the warning regarding the existing output directory. You should now also see a content directory and some configuration files.
Amend the following line in publishconf.py to ensure Pelican does not delete all content in the output directory prior site regeneration (including your git submodel repository!).
DELETE_OUTPUT_DIRECTORY = False
Creating Your First Article
All content in the Pelican source project should be written in Markdown or reStructured Text (rst). To begin, simply save the articles as .md or .rst files in the content directory (e.g. ghpages/content/create-github-page.rst). As your site grows you can consider alternate methods for organization.
I decided to use rst. You can use your favourite text editor or an IDE but I would recommend the Online RestructuredText editor. You can see the formatted output as you write which is very helpful. Note that it will look different in the final site once CSS is applied so don't get worried about font or anything like that yet.
Make sure to add metadata aligning with these requirements.
Update: After about three months of work with Pelican using reStructured Text I've settled to using PyCharm for editing & the options outlined below for previewing in a web browser. The option I recommended earlier is okay for quickly previewing how rst syntax works but is not practical for continuous editing, saving & HTML generation. To be honest, however, I'm considering switching to markdown due to the broader built-in support for editing & preview (Atom etc).
Building & Serving with HTTP
Build the site using the pelican utility. I would recommend using the -r or --autoreload option which will auto-reload the site allowing you to edit documents and review changes without restarting pelican.
cd /path/to/ghpages pelican content/ -r
Open a new shell session in a new terminal and start the Python simple HTTP server to preview how it will look when hosted by GitHub.
In Python 2:
cd /path/to/ghpages/output python -m SimpleHTTPServer
In Python 3:
cd /path/to/ghpages/output python -m http.server
Then navigate to http://localhost:8000/ and look at your site. You can edit any of your pages as you go and simply refresh your browser to see the results.
Once you are satisfied you can kill both the HTTP and pelican services with CTRL+C.
Before publishing, you want to generate the site again while including the publishconf.py settings. Based on our default set-up this will add absolute URLs which is important for various add-ons you may later want such as disqus comments.
cd /path/to/ghpages pelican content/ -s publishconf.py
Add, commit & push the files in the output git submodule.
cd output git add . git commit -m "First post." git push -u origin master
Once complete, do the same in the source repository.
cd .. echo '*.pyc' >> .gitignore #don't need pyc files git commit -m "First commit." git push -u origin master
Visit your site at http://you.github.io and see the results!
Before making a second post, you probably want to:
- create an about page within content/pages/about.rst
- pick one of the many awesome themes
In my next post I'll cover installing and applying themes.