Blogging

Technology, Resource Page
Page content

This blog uses Hugo and the Mainroad theme. Hugo is one of many static site generators. Static Gens are software suites that dynamically create sites using simplified markup languages such as Markdown. The sites don’t rely on PHP, Node.js, or other server side programming.

Static sites can look and feel like modern websites with no special software running on the servers. This allows you to (comparatively) easily create very nice websites and blogs without requiring expensive hosting, a really steep learning curve, and potentially risky services from a security perspective.

However, it’s still a pretty steep learning curve. I went with Hugo because I tried a few others and–without leaving my main account in administrator privileges all the time–I wasn’t able to get the others working.

Partly that’s my lack of expertise and partly it’s a lack of good documentation. This section won’t fix that but it may help a bit if you already know the command line on the operating system you’re using.

To get Hugo working with the theme I’m using:

  1. Install Hugo
    • If you’re on Windows, you’ll need to install git also
  2. Go to the command line
  3. Navigate to the location you wish to create your site in
  4. Type hugo new <sitename>
  5. Use cd to navigate to <sitename> and then to themes
  6. Use git clone https://github.com/vimux/mainroad to download the Mainroad theme to the theme folder
  7. Navigate one folder down (cd ..)
  8. Edit config.toml
  9. Paste the Config.toml example from https://themes.gohugo.io/mainroad/ into config.toml and use # at the beginning of the lines for disqusShortname, googleAnalytics, avatar, twitter_cards, and all lines of [Params.widgets.social]
  10. Remove "search", and "social", from the widgets line
  11. Change readmore = false to readmore = true
  12. Save the file and exit
  13. Navigate to content and create the folder posts
  14. Use Front Matter example from https://themes.gohugo.io/mainroad/ to start new posts
  15. You can remove the thumbnail, disable_comments, and mathjax lines
  16. Add menu: main if you want to add a post to the menu (like About and Resources above)
    • If you don’t want the same post showing up in your main feed also, save it at the root of content (not inside posts)
  17. To see the results of your work, run hugo server and connect to the address shown in the command line window using the browser of your choice
  18. To save the site in a way that you can upload to other places, just run hugo
  19. After running hugo, you can upload the contents of <sitename>/public to a webhost

Past that, it’s up to you. You can pick other themes if you like. They may have different instructions that need to be followed and may provide less guidance than Mainroad does.

Example post

I use this as a blank to start posts with. It started with something off Mainroad but I adjusted it to make it work for me. I added an example on how to build tables and how to use footnotes.

---
title: "Example article title"
date: "2018-09-03"
description: "Example article description (shows up in meta data)"
lead: "Example lead - visible text highlighted near the title"
authorbox: true # Optional, enable authorbox for specific post
toc: false # Change this to true if you want a table of contents. It will go at the top and I can't figure out how to change that.
categories:
  - "Category 1" # You don't have to have categories if you don't want. Just delete "categories:" and the two lines after that (i.e. this one and the next one).
  - "Category 2" # If you do want categories, leave "categories:" line in and modify the text between the quote marks on these lines before the hashtag
tags:
  - "Test" # You don't have to have tags if you don't want.
  - "Another test" # If you do want tags, leave "tags:" line in and modify the text between the quote marks on these lines before the hashtag
---

This is where your post content goes.[^1]

This | is
-----|---
A | table

[^1]: The pair of [^1] tags is how you make a footnote. You can use other numbers if needed.

Use <!--more--> at the end of a post if you don’t want any of it going behind a read more. To control where your read more is, put <!--more--> where you want the break.

It may also be a good idea to make your own example post and add all the categories and tags you’re planning on using regularly. That way you don’t have half of your Star Trek posts under #Star Trek and half under #StarTrek.

Add weight: 1 to your front matter to keep a post at the top regardless of other factors (i.e. to sticky a post). If you want a set of posts in a particular order, use 1 for the top post, 2 for the second post, etc. This orders your menubar too so if you have a post that should always be first in one context but second in another context, then you might need to give it a higher number but give its children even higher numbers.

For example, let’s say I want resources to show up in the menu bar but I want About to show up to the far left of the bar and Resources to show up after. However, I also want Resources to show up at the top of its own list. (For reasons, this actually doesn’t work but it’s not related to weight but because Resources has children pages …)

In that case, I assign a weight of 1 to About, a weight of 2 to Resources, and anything inside of Resources either gets no weight or a weight lower than 2.

Neocities specific notes

Don’t use drag and drop to copy your hugo site from your PC to your browser. Neocities will miss like half of your folders and put files in the wrong place. Use the CLI instead. I did it by hand once and it was a nightmare I won’t repeat. WebDAV was just as messy though, in fairness, I could have downloaded the dedicated software they recommended. But I’m not sure it would be better.

Steps, because at this point you need them:

  1. (Only Windows needs this step because Linux and Mac have it already … unless you have very old Mac or you have a weird Linux distro) Install Ruby
  2. In the command line, run gem install neocities
  3. In Neocities, go to your Account Settings
  4. Find your site and click Manage Site Settings
  5. Click API Key
  6. Click Generate API Key
  7. Go to the command prompt
  8. Navigate to <your site>/public
  9. Enter neocities push .
  10. Enter your site’s name
  11. Enter your password
  12. On Mac, stuff just worked at this point and it didn’t ask me for the API key (Not trying again in Windows to see if it does something different … sorry)
  13. It’s going to take a while
  14. Once it finishes, navigate to your site in your browser and make sure stuff worked

Note: It only asks you for your password once. Make sure your computer is secure and revoke your key inside the Neocities site if you have a concern at any point.