content/posts/hugo-github.md

   1 ---
   2 title: "Moving to Hugo and GitHub Pages"
   3 Description: "Moving to Hugo"
   4 date: 2020-06-03T14:00:00-04:00
   5 draft: false
   6 tags: ["general", "hugo", "github"]
   7 ---
   8
   9 ## Goal
  10
  11 I've been running my blog over on Ghost[^1] for a few years now. I really don't have a lot of issues with it, except for the fact that I have to manage the server itself. I've been running a small Digital Ocean VPS for a number of years where I host my blog. Ghost itself goes through a lot of updates and keeping the application up to date was starting to become a hassle.
  12
  13 I was keen to move to a solution where I could
  14
  15 - Write my posts in markdown
  16 - Not have to worry about hosting/management
  17
  18 After looking at a few different solutions I ended up settling on a static site that was hosted through GitHub. The benefits of this was that
  19
  20 - I could have all my content stored on GitHub.
  21 - I could utilize GitHub pages to serve the site with a custom domain name (with SSL)
  22 - I wouldn't need to keep everything up to date
  23 - I could re-purpose my VPS for other things
  24
  25
  26
  27 Of course, not all static sites are created the same. I specifically settled on Hugo to power my static site.
  28
  29 ## Hugo
  30 Unlike more traditional blogging software (WordPress, Ghost, etc.) which saves your posts in a database, Hugo[^2] generates a bunch of static files (HTML) for each post. By doing this you're still able to have the more complex features (tagging, drafts, pagination, themeing, etc.) but because Hugo pre-processes everything, you're just left with a bunch of HTML files that represent your site. Once you're happy, you can just sync the generated files with your server. In my case, I'm simply able to `git add` and `git push` my content to GitHub.
  31
  32 ### Dynamic Blogging Platforms
  33 Lets look at Wordpress to contrast Hugo. WordPress is the most used blogging software in the world and has the following requirements:
  34 - PHP
  35 - MySQL
  36
  37 The implicit requirement is also a server that supports these two. That means you are either relying on a 3rd party host that manages the server and just exposes the Wordpress interface... or you are managing that server yourself.
  38
  39 Most blogging systems work this way - Some language requirement, and some database system for storing the data you create.
  40
  41 However, there's lots of additional caveats that you aren't normally aware of, that tend to bite you later:
  42 - You need to run a web server, either Apache or Nginx
  43 - You need to keep the server itself up to date (security patches)
  44 - You need to keep Apache|Nginx/PHP/MySQL up to date (security patches)
  45 - You need to manage database backups (what happens if your server crashes)
  46 - You need to keep WordPress up to date.
  47
  48 That's a heck of a lot of stuff for something that's supposed to be easy. And I just picked WordPress because it's popular. Almost every blogging system is the same way.
  49
  50 Except for static site generators.
  51
  52 ### Static Site Generators
  53 Static Site Generators are a different way to approach blogging that merges more recent tooling with traditional delivery methods. That's just a fancy way of saying Static Site Generators give you some tooling to generate a bunch of HTML documents that represent your site.
  54
  55 With Hugo, I install hugo locally.. write some markdown for my posts, and then use Hugo to generate the HTML for my site. With this, we bring our "management" layer down to:
  56 - Hugo
  57 - Web server (nginx/apache)
  58 - The hosting server
  59
  60 Hugo runs locally, so the surface of attack is pretty minimal. There's nothing really wrong with running an outdated version of Hugo except you won't get the most recent features/bug fixes. But there's no security implications of doing so.
  61
  62 Since the output from Static Site Generators is just .. static content it can be hosted anywhere. You can use a hosting provider, a VPS, S3+CloudFront, or.. GitHub Pages!
  63
  64 ## GitHub Pages
  65 GitHub pages is a feature of GitHub that is available to all accounts, regardless of subscription. GitHub pages allows you to serve static content from any repository you'd like. They have some rules around how you need to organize your code and how to configure your site (project vs. main) but it's all relatively straight forward.
  66
  67 I haven't really hosted much on GitHub pages, but it's very easy - They also have a great walkthrough page[^3] that shows you how to configure the kind of Static Site you want to host.
  68
  69
  70
  71 ## Project Configuration
  72
  73 I'm not going to go into too much detail, because both Hugo and GitHub have very good introductions, but this should be enough to get a site running.
  74
  75
  76
  77 ### Installing Hugo
  78
  79 Installing Hugo can be done from a terminal in your chosen operating system. There are alternate installation instructions available if you don't have brew installed or if you don't have a mac[^4].
  80
  81 ```bash
  82 brew install hugo
  83 ```
  84
  85
  86
  87 ### Setup Hugo
  88
  89 Open up your terminal, and navigate to the place you want to store your website. Then you can run the following command:
  90
  91 ```bash
  92 hugo new site mysite
  93 ```
  94
  95 This creates a new folder called `mysite` that contains the raw files for your static site. At this point you don't have anything generated just the files that will eventually be compiled into your static site.
  96
  97 You can install a theme by doing the following:
  98
  99 ```bash
 100 git init
 101 git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
 102 ```
 103
 104 You can actually choose whatever theme you would like from https://themes.gohugo.io/  [^5]and just replace the `git submodule` line with the instructions from your theme.
 105
 106
 107
 108 Line 1 creates a git repository in the `mysite` directory. We want this because themes in Hugo are installed via `git submodule` which clones a particular repository into the current one. It also allows you to save the raw site (before static generation) to git!
 109
 110
 111
 112 Now it's time to head over to your `config.toml` file and set up the defaults for your website. My config file looks like this. You only really need the configurations on the first 9 lines. The rest are just further configurations[^6] that I've made.
 113
 114 ```toml
 115 baseURL = "https://xangelo.ca"
 116 theme = "plain"
 117 title = "Xangelo.ca"
 118 author = "Angelo R"
 119 copyright = "Copyright © 2011 - 2020"
 120 paginate = 15
 121 languageCode = "en-us"
 122 enableInlineShortcodes = true
 123 footnoteReturnLinkContents = "^"
 124
 125 [params]
 126 subtitle = "Technical musings and other tidbits"
 127
 128 [markup]
 129 [markup.highlight]
 130 lineNos = true
 131 lineNumbersInTable = true
 132 style = "vs"
 133 tabWidth = 2
 134 [markup.tableOfContents]
 135 endLevel = 3
 136 ordered = true
 137 startLevel = 2
 138 ```
 139
 140
 141
 142
 143
 144 ### Create and test!
 145
 146 Hugo ships with a built in server that allows you to preview what your site will end up looking like, you can start it up with:
 147
 148 ```bash
 149 hugo server -w
 150 ```
 151
 152 This creates the server and the `-w` flag sets it to "watch". Any changes that are made will automatically reload the server and also reload the site. You can visit this site by navigating to `https://localhost:1313` in your browser.
 153
 154 You can create a new post by using `hugo new posts/welcome.md`. This creates a new Markdown file in the `posts/` directory.
 155
 156 You can go ahead and edit that file - saving it will cause Hugo to live reload the website.
 157
 158
 159
 160 ### Publish your site!
 161
 162 Once you're happy with your stuff, you can turn off the live-reloading server and run the `hugo` command. This parses all your information and generates the static files for your website. It will then put all this content in the `public/` directory. If you followed the instructions from earlier around setting up GitHub Pages, you can `cd` into the `public/` directory and set it up as another git repository.
 163
 164 then running `git push `will publish your static files to whatever GitHub repository you configured to host the site.
 165
 166
 167
 168 ## Wrapping Up
 169
 170 I haven't really dug too much into setting up GitHub pages because it's mostly clicking around the interface and the instructions for that are kept up to date [^3]. I highly recommend GitHub pages because of the ease of setting up
 171
 172 - Custom domain names (if you have your own domain it's trivial to point it to your GitHub pages site)
 173 - Custom domain name SSL certificafte. Most places only allow you custom SSL certs if you use a subdomain, but GitHub lets you use a custom domain name.
 174
 175
 176
 177 I also highly suggest you spend some time going through the themes[^5] on Hugo to find one that you really like. There are so many and it's so easy to make new themes that you'll definitely find one you like.
 178
 179
 180
 181 ## Footnotes
 182
 183 [^1]: Ghost, a node.js based blogging engine: https://ghost.org/
 184 [^2]: Hugo, static site generatror: https://gohugo.io
 185 [^3]: GitHub Pages setup:  https://pages.github.com/
 186 [^4]: Hugo installation: https://gohugo.io/getting-started/installing
 187 [^5]: Hugo themes: https://themes.gohugo.io/
 188 [^6]: Hugo configuration options: https://gohugo.io/getting-started/configuration-markup