Refreshing Pelican

Posted by Mischa Fisher in Technology   
Tue 03 July 2018

Two years after rebuilding this site, Pelican - the python based static site generator I use - was in need of an update. Here's a brief summary of a few meaningful changes to the build:

(and kudos to my good friend and former Google/FB engineer Sahand Saba for leading the way on all of these changes)

Updating Math Rendering

The original version of this site used Mathjax to render LaTeX within Markdown, which worked well for displaying equations, but there was room for speed and bandwidth improvements. Enter Katex, "the fastest math typesetting library for the web".

It has a simple installation, no dependencies, and it's own CDN. The trick is removing the need to have in-browser javascript doing the rendering.

The github project file is here: https://github.com/Khan/KaTeX

Installation is as simple as a pelican_katex.py file referenced in the pelicanconf.py file:

```` PLUGINS = ['pelican_katex'] ````

And the repo here: Sahand Saba Katex Pelican repo

Configuring HTTPS for Amazon S3

Looking up at the URL bar, you'll notice everything is now being served in https. This is thanks to a link between Amazon Cloudfront and the S3 bucket that hosts this site.

Quick links to get started are here:

Versioning Using Bitbucket

Version control is a critical but often overlooked step not only embarrassingly frequently on the enterprise level, but also for many personal projects. Rather than running iterations of the site through copied folders hosted on my personal Dropbox account, I finally got around to version control using bitbucket. Git is of course more standard, but bitbucket provides free private repositories, which is a necessity for the backend python code being used to generate the site.

Favicon

Finally, there's now a favicon of the camera logo of the old soviet era camera that constitutes my personal site logo. There's a simple generator package available on github that can generate a favicon stack to work on just about any browser or platform.

Read more...


Customizing Pelican for Static and Dynamic Content

Posted by Mischa Fisher in Technology   
Sun 13 September 2015

This is a a brief summary of a few changes I think were extremely helpful in tweaking the stock Pelican build for a customized, statically generated website:

Rendering Math Markup

Mathjax seemed to be the simplest solution. Embedding the information via a short snippet of code linking to their CDN, and then using simple LaTeX notation within Markdown takes only a minute or two:

<script         src='https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>

Using Bootstrap for Responsive CSS

Erik Flowers Bootstrap grid introduction is a very nice resource (Click Here)

Customizing Your Own Theme

Web developer Robert Iwancz made a great bare bones framework on which one can build out almost anything. (Click Here for his VoidyNullness Theme)

Using Pelican for a Static Landing Page

Find your .md markdown file that you want to use as your home page content and add the following metadata to the top of the file: (the second change is to prevent your home page from appearing in the menu twice, depending on your theme).

save_as: index.html
status: hidden

Then in a separate .md file that will become your blog content, add the metadata identifier at the top to assign the appropriate HTML template from your templates folder:

Title: (Your Blog Title)
Date: (The Date)
Category: Page
Template: (the title of your blog template, without the .html extension

Finally, copy the content generating loops from the default page templates into your new blog html template:

{% block content_body %}
{% block article %}
{% if articles %}
  {% for article in (articles_page.object_list if articles_page else articles) %}
<article>
  {% for file in CUSTOM_INDEX_ARTICLE_HEADERS %}
    {% include "includes/" + file %}
  {% else %}
    {% include "includes/article_header.html" %}
  {% endfor %}

  {% if ARTICLE_FULL_FIRST is defined and loop.first and not articles_page.has_previous() %}
    <div class="content-body">
    {% if article.standfirst %}
      <p class="standfirst">{{ article.standfirst|e }}</p>
    {% endif %}
    {{ article.content }}
    {% include "includes/comments.html" %}
  </div>
  {% else %}
    {% include "includes/index_summary.html" %}
  {% endif %}
</article>

<hr />
  {% endfor %}
{% endif %}
{% endblock article %}

{% block pagination %}
<nav class="index-pager">
{% if articles_page and articles_paginator.num_pages > 1 %}
    <ul class="pagination">
    {% if articles_page.has_previous() %}
        <li class="prev">
          <a href="{{ SITEURL }}/{{ articles_previous_page.url }}">
        <i class="fa fa-chevron-circle-left fa-fw fa-lg"></i> Previous
      </a>
    </li>
{% else %}
    <li class="prev disabled"><span>
        <i class="fa fa-chevron-circle-left fa-fw fa-lg"></i> 
        Previous</span>
    </li>
{% endif %}

{% for num in articles_paginator.page_range %}
  {% if num == articles_page.number %}
    <li class="active"> <span>{{ num }}</span> </li>
  {% else %}
    <li>
      <a href="{{ SITEURL }}/{{ articles_paginator.page(num).url }}">{{ num }}</a>
    </li>
  {% endif %}
{% endfor %}

{% if articles_page.has_next() %}
    <li class="next">
      <a href="{{ SITEURL }}/{{ articles_next_page.url }}">
        Next <i class="fa fa-chevron-circle-right fa-fw fa-lg"></i>
      </a>
    </li>
{% else %}
    <li class …

Read more...


The Pros and Cons of Using a Static Site Generator

Posted by Mischa Fisher in Technology   
Sat 12 September 2015

In a recent effort to re-gear this site toward the quantitative and away from the strictly artistic, I rebuilt the site from scratch with one singular aim: make posting effortless. In that spirit, I was directed by a good friend toward static site generators; a new development in the 8 or so years since I had last looked at any of the technologies surrounding web development.

With the new site up and running, here is a brief list of the pros and cons, as I see them, of using a static site generator:

Pros:

  1. Effortless posting:

Write posts in Markdown, then upload with a few keystrokes straight from the terminal.

  1. Cheap and scalable hosting:

I'm using Amazon's S3 for hosting, and Route 53 for DNS services. They're almost free in low traffic, and infinitely scalable in high traffic.

  1. No backend to maintain:

PHP, SQL, and the slow load times and unresponsiveness of shared servers on most hosting plans are a thing of the past. (I'm looking at you GoDaddy.com)

  1. Easy to backup or migrate:

I have all the website files in the location of my laptop being backedup to Dropbox in realtime. In addition, version control through something like Git is also handy, particularly when messing around with the underlying Python scripts that generate the site.

Cons:

  1. Steep learning curve:

The list of technologies one has to look at include: HTML, CSS, Python, JavaScript, Markdown, the unix terminal, Pelican, FontAwesome, Jinja, Bootstrap, s3cmd, pip, brew, and virtual environments.

  1. Longer to get setup:

With a squarespace account you can be up and running in minutes. And it will look a lot prettier by default.

For me those were the biggest pros and cons I weighed in setting this site up. (Your mileage may vary.)

Read more...