Moving an Old Website to Github Pages: Creating a Finished Product

 In the last post I wrote about the process of creating the layout and the challenges through the content conversion and basic layout stages. This post works through some of the fine-tuning and the process of "going live" with the new site and its structure.

Seeing the Content is Believing

Throughout the content conversion process I would periodically push the changes to Github which would re-deploy the site. In the process, I noticed some complications with the setup. The material was all there, lots of it, and it was not easy to parse. It was time to fiddle with more layout.

General Readability and Layout Modifications

I don't have a good way to explain the process I used other than super tinkery and iterative (as the commit history shows). At times it would take several updates to effect a change, but it was successful to a point where the site was acceptable for the initial cutover.

Tagging and Categorization Review

Once I completed the sketches it became obvious that the tag and category pages are woefully devoid of useful content. More tags and categories are needed to make this functionality useful, but it also identified some layout and other peculiarities in their layouts which I fixed.

I also decided to include a "static" block for the holy grail category of content. Since the film content isn't a sketch, it's not going through the tag and categorization process of the sketches ... as designed. It's still useful to include a reference, so I added a block at the bottom of the categories.html page:

<section id="holy-grail" class="taxonomy-section">
	<h3 class="taxonomy-title">holy grail</h3>
	<div class="entries-{{ page.entries_layout | default: 'list' }}">
		<a href="/holygrail/#the-screenplay-index">See the Screenplay Index</a>
	</div>
</section>

Customizing the Styles

The magic sauce in this conversion was the ability to make local changes to the general theme in the main.scss file. In about 70 nicely-formatted lines of CSS all of the local style overrides are in place, and most deal with basic layout things. What I like most about this approach is that it's really consolidated all of my changes and limits the amount of hunting that may be necessary in the future.

Handling Holy Grail adds/strikes

As I've noted elsewhere in this series, the Holy Grail section is really a screenplay and as such includes content that was added and struck from the screenplay as it was filmed. It's important to keep this material and note it accordingly, and I decided to use a form of content highlighting that the So Simple theme affords, in particular, use of the .notice--warning and .notice--success styles, like this section at the end of Scene 8:

<span>~~**ARTHUR**: We have a task, we must waste no time! To Camelot!~~</span>{: .notice--warning}

<span>**GALAHAD**: God be praised!</span>{: .notice--success}

Wrapping the adds and removes in a span with the appropriate style applied (along with the ~~ strikethrough of content) maintains this integrity and better calls out the changes than what I'd done with the old site (merely a +/- visual at each line's beginning).

 Leveraging Github Features

Taking inspiration from the past with a bit of 21st century flair (how Microsoft now handles their documentation), I wanted to link an "edit" shortcut for each bit of content back to the source markdown in Github, where folks can self-edit a file and submit a pull request for consideration. I'm also pointing comments at the Github issues page rather than dealing with a contact form or email.

To make these changes I added a page-contribute.html include and point to it in the post.html layout:

<h3 class="page-taxonomies-title">Contribute</h3>
  <ul class="page-taxonomies">
    <li>
      <a href="{{ site.github_repo_file_path_base }}{{ page.path }}" title="Edit content" rel="tag"><svg aria-hidden="true" focusable="false" data-prefix="far" data-icon="pencil" class="svg-inline--fa fa-pencil" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"></svg> Edit content</a>
    </li>
    <li>
      <a href="{{ site.github_repo_url }}/issues" title="Suggestions" rel="tag"><svg aria-hidden="true" focusable="false" data-prefix="far" data-icon="comments" class="svg-inline--fa fa-comments" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"></svg> Suggestions</a>
    </li>
  </ul>

For clarity in this example I removed some of the SVG detail.

{% include page-contribute.html %}

Share and Share Alike

I also created a set of sidebar sharing links based on the same share options elsewhere in the theme (at the bottom of each page) and included it accordingly:

<h3 class="page-taxonomies-title">Share</h3>
<div>
  <a href="https://www.facebook.com/sharer/sharer.php?u={{ page.url | absolute_url | url_encode }}" title="Facebook" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" class="btn btn--facebook btn--small"><i class="fab fa-fw fa-facebook" aria-hidden="true"></i> <span> </span></a>
  <a href="https://twitter.com/intent/tweet?text={{ page.title | url_encode }}%20{{ page.url | absolute_url | url_encode }}" title="Tweet" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" class="btn btn--twitter btn--small"><i class="fab fa-fw fa-twitter" aria-hidden="true"></i> <span> </span></a>
  <a href="https://www.linkedin.com/shareArticle?mini=true&url={{ page.url | absolute_url | url_encode }}" title="LinkedIn" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" class="btn btn--linkedin btn--small"><i class="fab fa-fw fa-linkedin" aria-hidden="true"></i> <span> </span></a>
  <a href="https://reddit.com/submit?title={{ page.title | url_encode }}&url={{ page.url | absolute_url | url_encode }}" title="Reddit" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" class="btn btn--reddit btn--small"><i class="fab fa-fw fa-reddit" aria-hidden="true"></i> <span> </span></a>
</div>

{% if page.share %}
  {% include sidebar-share.html %}
{% endif %}

There's no longer a reason to pretend I don't have anything to do with the look, so might as well make it more easily sharable and open to a larger community, though it's unclear why someone might share this on LinkedIn!

Image Hosting

Several of the Holy Grail scenes also have screen capture images. These were hosted on the old site at a path outside the preserved TWiki structure. For the same reasons as untangling the site, I needed those to go elsewhere...and since the images are small it's easy to add them to the repo and link to them with an associated style for layout:

![Arthur and Patsy](/images/swallow1.jpg){: .align-right}

Google Analytics

I'd included the Google Analytics functionality in the So Simple theme, but my GA data indicated something was not configured properly as data was not being received. Looking a little closer, even though it shouldn't matter from what I could tell, the problem was in the template still using the old GA script block. So I "upgraded" it to use the gtag.js script block.

Making this change was a two-step process. First, creating the script block override google-analytics.html that uses the GA ID from the site configuration ({{ site.google_analytics }}):

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src='https://www.googletagmanager.com/gtag/js?id={{ site.google_analytics }}'></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', '{{ site.google_analytics }}');
</script>

The second step was to create an override of the scripts.html include that, for some reason, also had a copy of the errant GA script block. The override just needs to include the block:

{%- if jekyll.environment == 'production' and site.google_analytics -%}
  {% include google-analytics.html %}
{%- endif %}

A couple of hit tests after the next deployment and all was working as expected with the analytics. Are they necessary? Not really, but it is useful to be able to look at what folks might be pointing at after all these years.

Time to Go Live with a Custom Domain!

It was then time to light it up and do the proper cutover which included pushing out the new DNS subdomain (and configuring Github to use it, which is well-documented and easy to do). I chose to use python.mzonline.com due to the historical way the site had been used (mzonline.com/python was its original landing page in 1997).

Once the SSL certificate was set up and everything ready to go on Github, it was time to deprecate the old site and rewrite folks to the new.

Enter: the Magic of Rewrites

Since the old site was completely replaced, I could simply add a blanket rewrite and call it a day. However, there's a little more nuance to it and I wanted to make things work better than just a single catch-all.

First off was rewriting links from the Holy Grail scenes 1:1 to their new location. Through a stroke of luck (or genius), in the TWiki configuration I'd handled these in such a way that it aligned well with the new Github Pages structure:

Old path: /bin/view/Python/HolyGrailScene1, new path: /holygrail/scene1

I used a RewriteMap to convert anything to lowercase, and a relatively simple regex pattern and RewriteRule to handle the rest:

RewriteMap tolower int:tolower
RewriteRule ^/bin/view/Python/HolyGrail(.*)$ https://python.mzonline.com/holygrail/${tolower:$1} [L,NC]

This automatically and seamlessly handles all of the Holy Grail content conversion. God be praised indeed, Galahad.

I used a couple of increasingly generic rewrites for the rest of the old TWiki structure to get folks in roughly the same place:

RewriteRule ^/bin/view/Python/(.*)Sketch$ https://python.mzonline.com/sketches/ [L,NC]
RewriteRule ^/bin/view/Python(.*) https://python.mzonline.com/ [L,NC]

Due to the image hosting noted above I wanted to ensure any rogue links to the images (/python/hgimages/) continued to work served from the Github Pages site. And lastly, a generic rewrite for anything else still pointing at the old /python URL:

RewriteRule ^/python/hgimages/(.*)$ https://python.mzonline.com/images/$1 [L]
RewriteRule ^/python https://python.mzonline.com [L,NC]

None of these things needed to be in place, but it only seemed right to do what I could considering some of these paths have been referenced for upwards of 25 years and the most recent update to the old site had been nearly 15 years ago.

Finally, a well-placed (deserved?) rm -rf at the old /bin and /python directories to wrap it up!

What's Next?

I have created my own short list of things in the repo issues, namely going through and adding useful tags for the sketches and later referencing those in the source material list. I'm sure I'll consider other style changes as well but I'm happy this site has finally found a good home where others can enjoy (and possibly contribute).

I focused the initial change to the materials I'd partially or fully converted in the past (namely sketches and Monty Python and the Holy Grail screenplay), but I've also got the other films on my short list for a future iteration. Perhaps a rainy (or snowy) day or two in the future...