Kickstart Example Project

Let's use the Full Stack Python code to get up and running within just a few steps.

First, grab the code and put it in a directory named "fsp":

git clone git@github.com:mattmakai/fullstackpython.com fsp

We can already get the website working since it's already been generated in its current state by Pelican when I checked it in. Go to the "fsp" directory and use the built-in Python HTTP server:

python -m SimpleHTTPServer

Full Stack Python is now running on port 8000. Go to http://localhost:8000/ in your browser and you'll see the same site that's currently on fullstackpython.com. Note if you want to run more than one site at a time you can add a port number after "SimpleHTTPServer" to serve on a different port.

Now we need to install the dependencies to make changes to the site and regenerate the output. This step is the one part that takes a little more Python knowledge. We need to use pip to install Pelican, but first we need to make sure pip is installed. On Mac OS X's console:

sudo easy_install pip

On the Ubuntu command line:

sudo apt-get install python-pip

If you're not familiar with Python, you'll also want to look at virtualenv to isolate Pelican's dependencies. This will be important if you have more than one Pelican-using project and they are on different versions of Pelican. Python developers can just nod and move along here.

Full Stack Python's dependencies are stored in the fsp/source/requirements.txt file. Go to that directory and install Pelican:

pip install -r requirements.txt

That will fail if you're not using a virtualenv because you're trying to install these requirements into your base Python installation. If you don't want to use virtualenv at this point just put a "sudo" in front of the command.

We're ready to make a change now. Go to the fsp/source/content/pages/ directory and modify one of the files. For example, add another entry in change-log.rst then save the file.

Pelican needs to regenerate the website output before you can see the results in your browser. I've wrapped those changes in a Makefile stored in fsp/source/. Rather than explaining make here, let's just execute the commands manually that we need to regenerate the website:

cp -R static-html/* ..
pelican -t theme -s settings.py -o .. content
cp ../pages/* ../
rm -rf ../pages/

What's all that? Basically we're just:

• copying static files that Pelican doesn't touch (like CSS, JavaScript, and images) into our output directory
• regenerating the website HTML output with Pelican
• copying the files Pelican puts in the pages directory into the base directory
• deleting the pages directory

I wrap those commands in a Makefile to automate the execution of those commands. Note that there's a bunch of ways to make this build process more efficient. But once I got everything working I focused on writing and publishing. You should figure out what setup will work best for your goals.

Now the website is regenerated and you should see the changes in your browser when you refresh the page.

GitHub Pages

GitHub Pages is an easy and free way to host static websites. You just need to have a branch called "gh-pages" in your repository, then go into the application's settings through GitHub's user interface and enable GitHub Pages.

GitHub Pages settings through the user interface on their web application.

Fork the Full Stack Python repository or create a new repository with a gh-pages branch. Enable GitHub Pages under the application settings. Then you should be able to access your static website at [repo name].github.io.

One last note. You can point your host records for your DNS settings of a domain you own to 204.232.175.78 so the site will be accessible through your domain name. I use Namecheap as my domain name registrar so my host records for @ and www look like this:

Namecheap host records pointing to GitHub Pages IP address for fullstackpython.com.

That's all for now! You'll definitely want to check out the Pelican Getting Started Guide next for a thorough walkthrough of setting up your own new project.

If you enjoyed this post you should check out my Coding Across America and Full Stack Python projects, both of which are Pelican-powered websites with all code freely accessible on GitHub.