Minimalistic web site design

Maintaining a web site is very time consuming. Moving a web site to another tool or to another service provider can be truly awkward. Having burnt my fingers on this several times I have reached the conclusion that I must simplify my web pages as much as possible. This is my current policy:

• The web site must be easy to maintain
• It should be easy to inspect the source code
• The site code should be easy to edit by any editor
• One should not be locked-in to any particular site builder
• The pages should look decent
• Every page should be easy to save and print as a linear structure
• The procedure should work under Windows, Linux and MacOS

This eliminates most of the common popular solutions such as using WordPress. My conclusion is to use the ubiquitous Markdown format, possibly with some HTML additions. The stylesheet from Github is sufficiently nice, and can be extended by inline style directives if necessary. Menus and multiple columns should be avoided. GitLab has a good handbook with recommendations for writing MarkDown.

1. Write the Markdown code

Use your favourite editor to write the markdown code. The editor doesn’t really require Markdown support, because the Markdown format is very simple, but there is a number of free, open-source WYSIWYG Markdown editors available on the web. Personally, I use Markdown mode for Emacs.

Download the Github stylesheet github-markdown.css to your HTML directory and put the following code at the start of your web page source code:

<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
.markdown-body {
box-sizing: border-box;
min-width: 12rem;
max-width: 40rem;
margin: 0 auto;
}

@media (max-width: 767px) {
.markdown-body {
}
}
</style>
<article class="markdown-body">

If you intend to have MathJax mathematical formulas on the page, then add the following code:

<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
</script>

Put the following text at the end of the page:

</article>

2. Write math formulas using MathJax

If you added the preparatory code for MathJax, math formulas can be written using LaTeX syntax with some differences. Enclose inline formulas within \$$ and \$$ instead of $, and display formulas within \$ and \$ instead of $\$. Backslashes such as in LaTeX commands, \, need to be escaped as \\.

An example:

\$f = \\frac{1}{E\\left[ t \\right] } = { \\left\\{\\displaystyle\\int\\limits_0^\\infty\\,S(t)~dt\\right\\} }^{-1}, \\tag{1}\$
where
\$S\\left( t \\right) \\approx \\frac{\\Psi_1\\left[ a\\left(t\\right),b\\left(t\\right)\\right]} {\\Psi_1\\left[a\\left(0\\right),b\\left(0\\right)\\right]}\\exp \\left(- \\int\\limits^t_0\\lambda_1\\left[a\\left(u\\right),b\\left(u\\right) \\right]~du \\right) \\tag{2} \$

is displayed as

$f = \frac{1}{E\left[ t \right] } = { \left\{\displaystyle\int\limits_0^\infty\,S(t)~dt\right\} }^{-1}, \tag{1}$ where $S\left( t \right) \approx \frac{\Psi_1\left[ a\left(t\right),b\left(t\right)\right]} {\Psi_1\left[a\left(0\right),b\left(0\right)\right]}\exp \left(- \int\limits^t_0\lambda_1\left[a\left(u\right),b\left(u\right) \right]~du \right) \tag{2}$

For a great MathJax basic tutorial and quick reference, check out StackExchange.

3. Convert Markdown to HTML

You can use any of a number of Markdown-to-HTML converters to translate your markdown code to HTML. I use Pandoc.

4. Copy the files to a local copy of the web site

Copy the generated HTML and the auxiliary files from your local development directory to a local copy of the web site. Test that your local copy and its links work properly, e.g., by using a tool for checking broken links.

Finally, synchronize the local copy of the web site with your web server using an upload tool, e.g., rsync for Linux or WinSCP for Windows. Test that the site still works as intended. WinSCP has a convenient command for comparing the contents of a local and a remote directory: Files/File Custom Commands/Compare Files/.