New website design

Remco Bloemen

2014-02-27, last updated 2014-03-04

ABSTRACT: The goal is to create a modern personal homepage authoring environment. The homepage will contain technical material such as mathematical equations, graphs and computer source code but also essays and photo galleries. Special attetion goes to maintainability, efficiency and typographical excellence.

Requirements

Technical implementation

An unix like environment is assumed. The authoring environment will contain a number of small tools for different tasks.

Gnu Make

AsciiDoc

imagemagick

base64 (gnu coreutils)

html-xml-utilities

java and the YUI, Closure, … bins

Makefile

Building the stylesheet

Important

Make sure images are only referenced once. CssEmbed will simply replace all instances of an url with a data-uri, duplicate url(…) s will result in al lot of duplicate base64. In CSS this can be solved by factoring out all references to one entry using commas to seperate the selectors.

TODO: Build a better CSS compressor that can do this automaticallly.

Building the javascript

Note

Closure’s ADVANCED_OPTIMIZATIONS mode is very powerfull, but requires modifications in the source code of some libraries. I have given up on trying to get MathJax to work with it and jQuery also seems to give errors.

Building the pages

Preprocessing images

Compressing and uploading

Tip

Use SSH keys so scp won’t ask about a password. It will take a moment to set up, but it will save you a lot of time in the end.

Asciidoc

Beautifying the HTML output

The default configuration for AsciiDoc’s xhtml backend produces reasonable html, but it can be made lighter. For example, the headers wrap their content in div’s. To remove these unessecary tags, simply override the corresponding rules.

Simmilarly the [head] and [footer] tags should.

Adding a real table of contents

Asciidoc has support for producing content tables, however this means a piece of javascipt will be included in the header that produces the table of content on load. This violates or requirement of maximally preprocessed data. Besides, there is not even a good reason to do it this way; the javascript is about the size of the resulting html and all the information is there when asciidoc runs. Therefore the script has to go.

The hxtoc utility parses a html document and converts a sequence <!-- toc -- > into a table of contents based on unordered lists. To solve the problem this marker is placed in the appropriately in te header and the makefile is used to filter the results of asciidoc through hxtoc.

Autogenerating thumbnails

I’m proud of this one; given an image::[] macro it will inline a

Use unicode symbols for callouts

Please remove the newlines and tabs. This macro is expanded in the <pre> environment where the whitespace will show up.

Alternatively one could pick symbols out of the range “➀ ➁ ➂ ➃ ➄ ➅ ➆ ➇ ➈ ➉” or “➊ ➋ ➌ ➍ ➎ ➏ ➐ ➑ ➒ ➓”. Or even go for an entirely different set of symbols.

TODO: Use the actual symbols in the asciidoc source as well

Source Highlight

TODO: line numbers excluded from copy-paste

Final configuration file

Runtime functionality

Hypenator

Configuration hardcoded to British English and Dutch.

TODO: Auto insert zero-width-spaces ​ in CamelCase words and inner word boundaries like in FooNameSpace::FooClass::fooFunction(int,int)

MathJax

Perhaps in the future I could replace this with MathQuill or even a preprosessor

Todo