Dear Parlour, I Updated My Website

This letter was sent to my parlour mailing list on April 24th, 2019. It's about my recent changes to my website.

This document was written by me, emsenn, and is released for the benefit of the public under the terms included in the "License" supplement. It was made possible with financial contributions from humans like you. Please direct comments to my public inbox or, if necessary, my personal email.

This document was written as a piece of correspondence to a certain person or community, and should be read in that light.

This document was written when the events it discusses were contemporary. Information in it may now be incorrect, and opinions presented may be out of date.

It's been a while since I sent my last message to this mailing list. My apologies - my new job as a property manager took up more time than expected, and I tinkered too much with my computer so was unable to easily draft something new to write.

Yesterday I worked out those kinks and updated my personal website for the first time since late-January. (There's still a lot to update, but it's progress.) In this letter I'm going to just talk about the site for a bit - how it's laid out, and how it's made.

I received a lot of feedback about my homepage as soon as I started sharing it. In case it changes, at the moment it is a brief paragraph introducing myself, followed by a list of pages and subdirectories (and subpages), followed by an index.

It's funny how an index, like what books have, looks so out of place on a website's index page. Of course, part of why my index looks exceptionally silly is that it also includes all the indexed terms and entries from my fantasy canon, so has entries about the fictional region of the Farsteppes listed right next to entries about the real company Facebook. But, consequence of the site being made for myself, first.

This index page, and all the documents, are generated by Org-mode's publishing features, from my org directory that looks something like this:

~/org/
     |src/
     .   |eli.org
     .   |index.org
     .   |mit-license.org
     .   |theindex.org
     .   |theindex.inc
     .   |sitemap.org
     .   |...
     .   |dear-parlour-i-updated-my-website.org
     |templates/
     .         |setupfile0.org
     .         |setupfile-base.org
     .         |setupfile-css-simple.org
     |pub/
         |index.html
         |theindex.html
         |sitemap.html
         |...
         |dear-parlour-i-updated-my-website.html

The homepage - pub/index.html - is generated from src/index.org, which well, I'll just show you:

#+SETUPFILE: ./default-setup.inc
#+TITLE: emsenn's Documents and Resources
#+EXPORT_FILE_NAME: ../pub/index
#+INDEX: index!"emsenn's Documents and Resources"
* Introduction
My name is */emsenn/* and I'm a writer and developer. This website is
a repository of my work. It is in early development; it is messy and
hard to navigate. I apologize. Below is a alphabetical list of pages
and subdirectories, followed by an index of terms.
* Sitemap
#+INCLUDE: "./sitemap.org" :only-contents t
* Index
*/Note:/* This index contains every term indexed in every project, and
so is very long, and sometimes entries are confusing because they
assume you're viewing them in the context of the project.
#+INCLUDE: "./theindex.org" :only-contents t

The line beginning with #+SETUPFILE specifies the file ~/org/templates/setupfile0.org - here's what that looks like:

As you can see, it includes two source files itself, setupfile-base.org and setupfile-css-simple.org. Here's what those look like. First, setupfile-base.org:

Then, setupfile-css-simple.org:

Most of my website's CSS is coming from the Ox-html defaults - that's what Org-mode uses to turn org files into HTML.

So, the index page is some basic configuration, some CSS, then the title, an introduction, and then it goes on to include sitemap.org and theindex.org. Both of those are long files, so I'll just say, sitemap.org is a list of links to the website's pages and subdirectories, and theindex.org includes theindex.inc, which has headlines for every letter, followed by a list of indexed terms with links to their relevant entries.

So, that's it for the homepage. Now let's look at a random document - like this one.

So this document starts the same way index.org does, with lines similar to the following.

#+SETUPFILE: ~/org/templates/setupfile0.org
#+TITLE: Dear Parlour, I Updated My Website
#+EXPORT_FILE_NAME: ../pub/dear-parlour-i-updated-my-website
#+INDEX: letter!by audience!to my parlour!"Dear Parlour, I Updated My Website"

Most of my documents start with an "Introduction" section which provides contextual information for the document. The "Introduction" section usually starts with a few sentences explaining the intent of the document, and are then followed by some standardized disclaimers about the document. To make that easier for myself, I've made up a source document just for that purpose - eli.org, "Editorial and License Information." Sections from that file are included as needed to provide context for the document - the file has quite a few sections.

For example, in this document, I include two sections: #eli, "Editorial and License Information" itself, and #document-context-correspondence, "Document Context: Correspondence."

The former discloses that I wrote the document and release it under the license attached, and the latter discloses that the document was originally written for a specific audience, and should be read in that context.

Under the "Introduction" section is a section containing the document itself. Finally, there's a "Supplements" section which, among other things, includes the mit-license.org file; the MIT License, which is what this document is released under.

So that's an explanation of how my documents look, on the source side: mostly just the document, but with some other stuff included to reduce how often I need to repeat myself.

In order to turn those org files into the HTML files in pub/, I run the command =org-publish-project, publishing the personal-website project.

This recursively looks through the src/ directory and exports each org-file into an HTML file in the pub/ directory. It then generates sitemap.org and index.org, and exports those as HTML files as well, into the pub/ directory.

From there, I run the command neocities push from inside the pub/ dir, which updates emsenn.net, which uses the host Neocities.org.

That's it - how I updated my website. I hope y'all like it. My next steps are just cleaning up the files that are already there, making sure they have proper listings in the index, but then I'll be looking to tweak the documents more; adding navigation, for example. I'm also going to be giving some thought to how to generate more modern website content, like a page outlining my recent activity.