Blogging on ~grandline

Feature: Blog

Overview

This guide will explain how to manage a blog using the scripts I've written on ~grandline that make the process easy for new users. We will be using Pelican, which is a static site generator written in Python. This means that your blog is only updated when you tell Pelican to read all your posts and format them to look nice. Your general work flow will be something like this:

Write a new blog post
Save it to ~grandline
Tell Pelican to update your blog

For most users, this will look like:

Write a new blog post on your local computer and save it as plaintext with the .md extension
Send it to ~/pelican/content/ on ~grandline using FileZilla
Login to ~grandline and run the blog command

Setting up Pelican

To get up and running is really easy if you don't mind using the defaults. All you have to do is login to ~grandline and run setup-blog in the command line. It will prompt you for some info about your blog (note that everything can be changed later) then copy the example content from /home/share/pelican/ and customize it with your entries. This creates a new directory in your home folder, ~/pelican/, which contains everything Pelican needs to manage and generate your blog.

If you want, many settings can be configured by editing ~/pelican/pelicanconf.py. For example, you could change the title of your blog or specify a new theme to use. If you don't know what a setting does, I recommend you don't change it. You can find my theme at /home/laptopdude/pelican/themes/dude if you want to look at it, copy it, or tweak it for yourself. You can also find many themes at this gallery and install them by asking me or directly from the Github.

Pelican will output to ~/public_html/blog/ and so your blog will be at grandline.jahschwa.com/~user/blog. Again, this is configurable, and you can update your index.conf to reflect any changes you make to the location of your blog. If everything is setup correctly, you will see a post-it note on the Pirates page in your row and the "Blog" column that links to your blog's home page.

Writing a Blog Post

Although there are many different formats available, we will be using the Markdown language. Note that your post should be in plaintext, which is most easily achieved with Gedit, Geany, Notepad, or Notepad++ depending on your system. The first several lines in your file provide info about the post like date, title, and tags. Everything after that is the actual post content. Here's an example blog post below. To view what it looks like with my theme, view the post on my blog.

Title: My First Blog Post
Date: 2015-04-12 13:44
Modified: 2015-04-12 13:44
Category: News
Tags: update
Slug: first-post
Authors: JAH-schwa
Summary: My first post

This is my first blog post! Yay, it works!

Check out the footer for links to the software I'm using.

Most of the starting info is pretty obvious, but I'll explain each item in the list below:

Title — the title that appears at the top of the post
Date — the date and time the post was created (use the above format)
Modified — the date and time the post was last edited (must be set manually)
Category — a broad category for the post (in default theme, these become menu links)
Tags — more specific areas of interest (separate multiple with commas)
Slug — the last segment of the web address (must be unique)
Authors — who wrote the post (should match what you specified in setup-blog)
Summary — a short blurb summarizing the post

Saving a Post to ~grandline

You can do this using any method discussed in the transferring files tutorial. For most users, this will probably mean creating the file locally and copying it to ~grandline using FileZilla. Your blog posts go in the ~/pelican/content/ directory, and must end in .md to signify markdown. You can name them whatever you want, although I personally like naming them with the date then title, for example 2015-04-12-first.md.

Updating Your Blog

If you are using all the defaults from this guide, you can use my update script. Every time you make a change to a post or create a new one, just run blog on ~grandline. This will tell Pelican to read through your posts and output the HTML for your blog.

Adding Media

Links

It's very easy to add links using markdown. You can add in-line links as shown below, where the link appears as "Google" and goes to google.com:

This is a link to [Google](google.com).

Or you can use the easier to read reference format, where the link will appear exactly as it does above:

This is a link to [Google][1].

 [1]: google.com

Images

It's also very easy to add images. You can either link to an image on the web, or create the directory ~/pelican/content/images/ and save them there. Below I give an example for both of the above. Note that "Gerrymandering" and "My Image" are displayed when you hover the mouse over it.

Here is an image from the web:

![Gerrymandering][1]

Here is an image from ~grandline:

![My Image][2]

 [1]: https://jahschwa.com/img/gerrymandering.jpg
 [2]: images/myimage.jpg

Videos

The best practice here is usually to copy some HTML code from the "embed" link on the video site. For example, on YouTube click on the "Share" link below the video, choose the "Embed" tab, and copy and paste the text into your post like in this example:

Here is a song created from the number pi:

<iframe width="420" height="315" src="https://www.youtube.com/embed/YOQb_mtkEEE" frameborder="0" allowfullscreen></iframe>

Files

If you want to link to files I recommend you keep them somewhere in your public_html folder rather than in your ~/pelican/content folder since Pelican will simply copy them to ~/public_html/blog, and if they're big files having duplicates could quickly eat up space. However, if you do want to do so, you can create a new directory in ~/pelian/content/mydir and add it to your ~/pelican/pelicanconf.py file by editing or adding the line: STATIC_PATHS = ['images','mydir']. Just separate multiple directories with commas.

Feed

You can enable Atom or RSS feeds for your blog so that anyone with a feed reader will receive a notification whenever you update your blog. To enable the Atom feed, just find the line in your ~/pelican/pelicanconf.py that says FEED_ALL_ATOM = None and change None to 'feeds/all.atom.xml'. To enable the RSS feed, just add FEED_ALL_RSS = 'feeds/all.rss.xml'. Most themes should have feed autodiscovery implemented by default, but if not you can link directly to your feeds with grandline.jahschwa.com/~user/blog/feeds/all.atom.xml and grandline.jahschwa.com/~user/blog/feeds/all.rss.xml.

Conclusion

If you want to tweak Pelican more yourself, you can check out the Pelican documentation. For more on markdown and what you can do with it see the Markdown documentation. For custom themes getting to know HTML and CSS is a good idea. Other than that, have fun, be polite, and share something awesome!