Choosing How To Write A Site

Just Write Plain HTML

There is more than one way to write a web page. The most direct way looks best to me.

Web pages go out to the world as text marked-up with HTML codes. Why not simply write them that way?

I studied advantages and disadvantages of different, alternative approaches during the past year. Every web page authoring scheme that does not involve writing HTML directly will, instead, oblige an author to mark-up text in other ways.

The Jekyll site construction system popularized by GitHub Pages gives an example. Its advantage features the markdown syntax for marking-up text.

Markdown syntax may appear to be simpler, at first sight, compared to HTML syntax. However, it must be converted into HTML eventually. Jekyll does this behind the scenes.

So that it may render this service, Jekyll expects the author to create further layers of special codes that must be written in Liquid, YAML or JSON syntax. In other words, using Jekyll to avoid one syntax, HTML, obliges the author to master two or three other, different syntaxes instead.

Back in the Flat Earth era, children were told that Earth was like a platter balanced on the back of a turtle, which in turn, walked around on the back of another, larger turtle underneath it.

And what is underneath the second turtle? an impertinent child would inevitably ask.

It's turtles all the way down, was the answer.

A system such as Jekyll is like those turtles, one markup syntax riding on the backs of other, different syntaxes. It's markup all the way down... until it ends up as HTML.

Cut out the middleware and its complexity if you can, say I. Simple pages like these I publish here on Neocities are easily written with HTML markup in the original text.

Since a web author must incorporate markup of some kind into the text for a page, why not let it be HTML? The syntax is no more demanding than any other, nor is it particularly difficult to learn. Practice makes better.

It does help — a lot — to work with a text editor designed to assist with HTML syntax. Such aid may include using color to distinguish markup visually, along with automatic indenting to help humans stay oriented in the text.

The Big Three editors described in a previous article — Nano, Vim and Emacs — can help that way. Some of the graphical text editors provided by the Windows and Mac operating systems might also, perhaps as an optional user-preference. This article does not try to explain how.

One thing that Jekyll can do, when combined with code provided by Liquid, is to prepare and to update intra-site links throughout all of the page files in a site. This ability enables static web sites built with Jekyll to mimic certain appearances of dynamic sites such as those using Wordpress.

I use Jekyll deliberately for this reason to maintain and add pages to a sibling web site, GardenCat.

Writing pages one at a time, in a text editor, calls for a different approach to such links. Actually, there are two sorts of internal links and I have addressed them in different ways in various other places.

One way is just to write the internal links into a page in the same way as writing links to other places on the web. I have been doing it that way in this site for the links to previous posts.

One of my goals is to write a short program designed to insert a current list of links into some or all of the page files in a folder. It would empower me to update links in all the files by merely editing that list then running that progam.

That is a dream, and if I make it happen then I will share it here on this site in a future article.

Another kind of internal link involves navigating to different sections within the same page. I have written a couple of short programs for that purpose. They are described on a sibling web site, The Code Diarist, in the following articles:

The Code Diarist also follows an alternative plan for navigational links to other pages throughout the site. Each page carries a link to the one before it and, if available, to the one following it. The home page provides links to all of the pages, grouped by month and also by topic. I simply add links to these places for each new page as I write it.

It is really not important to me that my web sites look exactly as though they were spewing forth from Wordpress.