Skip to Content

Brief Explanation of My Website Method

I was asked by a couple people how I’m making my website. This will be brief and colloquial, since I plan on documenting it properly within the projects’ sources itself. It’s mostly written to them, and has that tone.

First, you can view my website’s source at https://emsenn.net/computer-instructions/personal-website/ and https://emsenn.net/computer-instructions/hugo-personal-website-theme/.

Alright so, my website has two core pieces, that I’ve just linked to:

For speed and clarity I’m gonna call them PW and HT - personal website and hugo theme.

Let’s look at it working backward from the public website at emsenn.net.

That’s deployed by Netlify, which reads it from a repository on Gitlab.com. That repository contains the HTML files and images and stuff that make up the website. To be clear: the public HTML files (PHF), the finished site, is in its own Git repository, wholly separate from the PW and HT repositories.

The files in the PHF repo are created by Hugo, which is a static site generator that takes specially formatted Markdown and turns it into a featureful website. (Though I’ll highlight my website doesn’t have many features at the moment. I’m always tinkering, though!)

Sorry for the tangents; as I said this’ll be colloquial, and well, I live in the American South. Be happy I’m not relating all this back to what happened at the church market last month, comparing it to how Amy gets her jams ready.

Anyway: So, the website at emsenn.net is put there by Netlify, which is watching a repo on Gitlab.com, which I put HTML files into, which are created by Hugo by reading specially formatted Markdown files. Pretend there’s a break for questions here. If you’re confused, stop here and come message me. In the next section I’ll talk about how I make those Markdown files.


So, how do I make the Markdown? By using Ox-Hugo to on Org-mode files (or just sections of one).

Org-mode is a way of marking up text that’s kind of like Markdown, but has a lot more features. Those features are implemented in the Emacs text-editor, which is what I use: you’ll have to use it too, if you want to follow my method. (I think you should, too, but that’s irrelevant: you have to if you want to follow these instructions.)

This part of the process is always tricky to explain, so let’s look at this essay. it exists in its own Git repo, words, and in that repo there’s a source.org. The top of that file looks like this:

#+author: emsenn
#+hugo_base_dir: ~/src/personal-website/

This sets up the author and where the root of my personal website is, “root” from Hugo’s perspective. In the word’s source file that we’re looking at, there’s a headline for Essays. That headline looks like this:

* Essays
  :PROPERTIES:
  :export_hugo_section: essays
  :END:

This tells Hugo to put every subsection we export from this one into the content/essays/ directory, relative to the base directory we set up earlier.

Finally, this essay’s title and info looks like this:

*** Brief Explanation of My Website Method
    :PROPERTIES:
    :export_file_name: brief-explanation-of-my-website-method
    :topics:   Hugo; Markdown; Netlify; Org-mode; Ox-Hugo; websites, personal; websites, development;
    :END:
I was asked by a couple people how I'm...

This doesn’t mention Hugo at all, but the export file name is the filename to save this as, minus the extension. So when I export this subsection from the words source file, it’ll go to ~/src/personal-website/contents/essays/brief-explanation-of-my-website-method.

And when I use Hugo to rebuild the website, it’ll make a file in the public HTML repository, essays/brief-explanation-of-my-website-method/index.html.

And when I use Git to push these changes to Gitlab.com, Netlify will grab them and put it at https://emsenn.net/essays/brief-explanation-of-my-website-method/index.html (which, to be clear, doesn’t need the “index.html” to be visited, I’m just being explicit.)

In Emacs, exporting a subsection like that is easy with hotkeys: Ctrl-c, Ctrl-e, H, H.

The “Native Content” in my personal website’s source file is exported to the hugo section “.”, which means “none” in this context. And so, the “Support” subsection is exported to content/support/, and ends up at https://emsenn.net/support. I can export every file in the subtree with Ctrl-c, Ctrl-e, H, A.

For pages that represent entire files, like my website’s source file at https://emsenn.net/computer-instructions/personal-website/, they have text like this at the start of their file:

#+export_file_name: ./personal-website
#+hugo_base_dir: .
#+hugo_section: computer-instructions

The Hugo personal website theme is the part that lets Hugo know how to take the Markdown Ox-Hugo makes and turn it into HTML. You can use other themes, so I’ll not really explain it here.

So, my flow:

A lot of this could be much more automated, but I change how I do my website frequently so I haven’t seen fit to automate anything yet.

I think that’s the best explanation I can do in a vacuum - if you have any questions, come ask them!

Editorial and License Information

My name is emsenn and I wrote this essay for the benefit of the commons. To the extent possible under law, I have waived all copyright and related or neighboring rights to it. If you're viewing it on a remote server, you're encouraged to download your own copy. Essays like this are made possible with financial support from readers like you. Thank you. To read more of my work and to learn more about me, visit https://emsenn.net