Our crew is replaceable. Your package isn't.

This Website

Construction

This site is created using Pelican. Pelican has a number of useful plug-ins and themes. The webpages and/or posts can be written in restructured text (rst) or markdown (md) and uses python's doctools to convert it into a web site.

Useful Commands Descriptions
make html creates the website
make clean deletes the current website output

Setup

The pelican configuration file (peliconconf.py) I used is shown below:

#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals
import logging

# coloring code snipets
# pygmentize -S monokai -f html -a .highlight > pygment.css
# pygmentize -f html -a .highligh > pygment.css

AUTHOR = u'walchko'
SITENAME = u'Planet Express'
SITESUBTITLE = u"Our crew is replaceable. Your package isn't."
SITEURL = 'http://walchko.github.io'

PATH = u'content'

# DELETE_OUTPUT_DIRECTORY = False don't use this, it wipes the .git directory

TIMEZONE = u'US/Mountain'

DEFAULT_LANG = u'en'

LOAD_CONTENT_CACHE = False

# Feed generation is usually not desired when developing
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None

DEFAULT_PAGINATION = 1000

PLUGIN_PATHS = ['./pelican-plugins']
# PLUGIN_PATHS = ['../pelican-plugins']

PLUGINS = ["render_math", 'code_include', 'sitemap', 'gist_directive']
# render_math - latex equations
# sitemap - for spiders, listed in robot.txt
# code_include - include code from other files
# gist_directive - link to gist code snippets

MATH_JAX = {'align': 'left'}

LOG_FILTER = [(logging.WARN, 'Empty alt attribute for image %s in %s')]

USE_FOLDER_AS_CATEGORY = True

STATIC_PATHS = [
        'blog/engineering/pics',
        'blog/macOS/pics',
        'blog/raspbian/pics',
        'blog/raspbian/static',
        'blog/robots/pics',
        'blog/robots/static',
        'blog/cyber/pics',
        'blog/computers/pics',
        'blog/arch_linux/pics',
        'blog/programming/pics',
        'blog/programming/static',
        'blog/repo/pics',
        'pages/pics',
        'pages/Publications',
        'extra/robots.txt'
]

EXTRA_PATH_METADATA = {
        'extra/robots.txt': {'path': 'robots.txt'}
}

# used by sitemap plugin and robots.txt
SITEMAP = {
    'format': 'xml',
    'priorities': {
        'articles': 0.5,
        'indexes': 0.5,
        'pages': 0.5
    },
    'changefreqs': {
        'articles': 'monthly',
        'indexes': 'daily',
        'pages': 'monthly'
    }
}

# PYGMENTS_RST_OPTIONS = {'linenos': 'inline'}

# number of words in a summary
SUMMARY_MAX_LENGTH = 100

DEFAULT_DATE_FORMAT = ('%a %d %B %Y')

THEME = './themes/kevin2'

ARTICLE_URL = "posts/{date:%Y}/{date:%m}/{slug}"
ARTICLE_SAVE_AS = "posts/{date:%Y}/{date:%m}/{slug}/index.html"

CATEGORY_URL = "category/{slug}"
CATEGORY_SAVE_AS = "category/{slug}/index.html"

TAG_URL = "tag/{slug}"
TAG_SAVE_AS = "tag/{slug}/index.html"

MENUITEMS = (('About Me', 'about.html'), ('Colophon', 'colophon.html'), ('Topics', 'categories.html'), ('Blog', 'archives.html'))

# Uncomment following line if you want document-relative URLs when developing
RELATIVE_URLS = True

Makefile

To build the website I do: make html

SHELL=/bin/bash
PY?=python2
PELICAN?=pelican
PELICANOPTS= -D

BASEDIR=$(CURDIR)
INPUTDIR=$(BASEDIR)/content
# OUTPUTDIR=/Users/kevin/github/walchko.github.io
OUTPUTDIR=$(BASEDIR)/www
CONFFILE=$(BASEDIR)/pelicanconf.py

GITHUB_PAGES_BRANCH=master

DEBUG ?= 0
ifeq ($(DEBUG), 1)
        PELICANOPTS += -D
endif

RELATIVE ?= 0
ifeq ($(RELATIVE), 1)
        PELICANOPTS += --relative-urls
endif

help:
        @echo 'Makefile for a pelican Web site                                           '
        @echo '                                                                          '
        @echo 'Usage:                                                                    '
        @echo '   make html                           (re)generate the web site          '
        @echo '   make clean                          remove the generated files         '
        @echo '                                                                          '
        @echo 'Set the DEBUG variable to 1 to enable debugging, e.g. make DEBUG=1 html   '
        @echo 'Set the RELATIVE variable to 1 to enable relative urls                    '
        @echo '                                                                          '

html:
        $(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS)

clean:
        [ -d $(OUTPUTDIR) ] && cd $(OUTPUTDIR); rm -fr *

.PHONY: html help clean

Publishing

I use travis-ci publisher to build and publish to my github website. The yaml file below uses a github access token to push the pages to the gh-pages branch.

language: python

# env:
#     global:
#         - COMMIT_AUTHOR_EMAIL: "kevin.walchko@noreply.github.com"

git:
    submodules: false

before_install:
    # - git submodule update --init --recursive
    - rm -fr pelican-plugins
    - git clone --recursive https://github.com/getpelican/pelican-plugins


install:
    - pip install -U pip setuptools wheel
    - pip install -U typogrify Markdown
    - pip install -U pelican

script:
    - make html


deploy:
    provider: pages
    skip_cleanup: true
    github_token: $GITHUB_TOKEN  # Set in travis-ci.org dashboard
    local_dir: www
    project_name: walchko.github.io
    repo: walchko/walchko.github.io
    target_branch: master
    on:
        branch: master

Pygments

To setup the css for code, I do:

kevin@Logan pelican $ pygmentize -S default -f html > pygments.css
kevin@Logan pelican $ mv pygments.css themes/kevin/static/css/
kevin@Logan pelican $ make html