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.
Dear Parlour, I Updated My Website
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
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-css-simple.org. Here's what those
look like. First,
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
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.inc, which has headlines for every
letter, followed by a list of indexed terms with links to their
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
For example, in this document, I include two sections:
#eli, "Editorial and
License Information" itself, and
"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
This recursively looks through the
src/ directory and exports each
org-file into an HTML file in the
pub/ directory. It then generates
index.org, and exports those as HTML files as
well, into the
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.
This document was made possible with contributions from humans like you. Thank you! I currently accept contributions through the following platforms:
If there is another service through which you'd like to contribute, please send an email. Please note that in accordance with my personal directives #003 and #018, I release all useful information I create for free, so financial contributions do not entitle you to access to any "exclusive content."
Copyright 2019 emsenn
Permission is hereby granted, free of charge, to any person obtaining a copy of this document and associated media files (the "Document"), to deal in the Doftware without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Doftware, and to permit persons to whom the Doftware is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
The Document is provided "as is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, or noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort, or otherwise, arising from, out of or in connection with the Document or the use or other dealings in the Document.