As became clear from my closing remarks in Dispose of Typo3 I am a strong proponent of static web sites. They run faster than any CMS and do well on inexpensive servers featuring little more than an Apache 2.4. and perhaps shared with dozens of other customers.

Of course, no one would get far by editing many .html files directly. Instead one would assemble or generate the site from neat text blocks – a collection of source files in a manner of speaking – with tools on the client workstation best featuring test and preview.

Ideally this generator also runs on the version control system server for said source files. In the case of SVN a post commit*) hook would generate the site and transfer changed content etc. to the web server**).
Note *):  In the case of GIT it would be a “post push hook”.
Note **): The SVN server and the (Apache) web server must not be on the same machine for this comfort for web authors.

I’ve used static site generation for over twelve years with Frame4 based tools. Starting 2019, I switched my web sites as well as those I’m in charge of to Jekyll / Liquid.

A a small dose of PHP – trick #1

Despite all advantages of static sites compared to those generated at request with PHP (Mostly, seldom Java) and DBS by the web server one might need a server information, some times. One example is displaying the account name of a user currently logged in. That’s trivially easy on the server with PHP, e.g., and virtually impossible for programs (probably JavaSript) running on the client.

Though Jekyll is totally unaware of PHP we can put a bit PHP in a page by its markdown and make Jekyll generate .php instead of .html. Excerpt:

---
layout: weAutSimple
.....
headline: Users and Accounts
permalink: userInfo/index_en.php # for production
# permalink: userInfo/index_en.html # to test appearance
copyrightYear: 2020
---
-(%- include referenceLinks.txt %}-(%- raw %}
<?php $user_account = $_SERVER['REMOTE_USER']; ?>-(% endraw %}
Some of our informations and [services][enServer] require 
authentication. If you read this, you've successfully logged
in with the weinert-automation (domain) account
<b>-(% raw %)<?php  echo($user_account);?>-(% endraw %)}</b>.
...

Note: Replace -( with {. Due to a bug Jekyll would execute code in an markdown code example instead of just displaying it.

As the excerpt shows

• injecting a bit PHP is done by the raw/endraw tag pairs and
• generating .php instead of .html is ordered by permalink in the front matter.
  permalink also works for “normal” pages not just for posts.

You may see the result on weinert-automation.de/userInfo/index_en.php when logging in as guest:guest. The Jekyll development server won’t display a .php page. Hence, the testing has to be done on the real server.

This trick #1 wasn’t invented by me but found in many places. What I missed (and tried to put here) was a complete presentation of all vital points.

Remark July 2021: After more than one year of usage trick #1 stopped working with no known reason or cause. Jekyll will handle “raw” no longer as “raw = kepp it exactly as is”. Between ‘raw’ and ‘endraw’ < and > will now be replaced by &lt; and &gt; turning PHP statements to visible text.
Rescue for above use case: PHP goes to the template, there putting ‘REMOTE_USER’ as text into a hidden ‘span’, from whence JavaScript will transfer it to the target (another span defined in the markdown text). It works – but, alas, is outright ugly.

Trick #2 on the other hand, I did “invent” and develop to working state. Most probably, I would not be the first one, but I was unable to find anything about it.

Apache’s fancy indexing with head and foot – trick #2

The Apache web server will generate very nice – or even “fancy” – directory listings

• for those directories you explicitly allow that by
  Options +Indexes or Options +FancyIndexing, e.g., and
• when the directory in question does not contain a file listed by DirectoryIndex, usually index.html, index.htm and index.php.

For nice indexing one may provide two html page fragments to be put before and after the directory table generated by Apache. They are

• configured by options HeaderName and ReadmeName and are
• called consequently pub-header.htm and pub-footer.htm in my case.

Those fragments pub-header.htm and pub-footer.htm can be held and maintained in the respective directories. Kindly, Jekyll will copy them to _site from whence the deployment process will transfer them to the (real) web server.
So far no problem. But besides that having pub-header.htm and pub-footer.htm is a nuisance:

1. HTML aware Eclipse will mark both with a lot of errors as they (must) have a lot of unclosed respectively unopened tags. This renders Eclipse’s HTML syntax checks virtually useless for those files.
2. You can’t see / check them while developing as, alas, Jekylls test server cannot index – be it fancy or not.
3. Partners and customers well acquainted to Jekyll and Markdown may get confused by HTML fragment files – not visible as said.
4. Those pub-header.htm and pub-footer.htm contain a lot of repeated code contradicting the static site generating philosophy.

The idea respectively trick to remedy this situation is simple by itself – but partly a bit tricky in realisation:

1. From each distinct pair of pub-header.htm and pub-footer.htm make one index.htm – not .html as all others.
   Advantage: Eclipse is happy andJekyll’s test server shows them (with no index table).
2. Find the commons and little differences easy to handle and make an according layout file. As all your directory listings should look alike one layout file should suffice, _layouts/weAutDirHF.htm in my case.
3. At the union point of the former pub-header.htm and pub-footer.htm insert a line with only a distinct html comment:
   <!-- Apache 2 fancy directory index -->
4. Now turn all remaining pub-header.htm and pub-footer.htm or index.htm to index.md referring to the layout just made (weAutDirHF.htm).
5. Let those index.md be generated to index.htm – not .html as all the rest.
6. In the deployment process, only, split all files index.htm at said HTML comment line to pub-header.htm and pub-footer.htm.

This split will be made by

  csplit index.htm "/^<small>listing generated by/"
  mv xx00 pub-header.htm
  mv xx01 pub-footer.htm

on the Linux (web server) machine and the Windows (development) workstation. csplit is a Linux tool, but will be available on Windows, too, when you have WinRaspi, WinAVR or the like installed and their tools on the PATH.
All other details may get clear by reading the (real) example files.

Hyphenation

For many tools and editors this is no bright story even when the language is mere English – and Jekyll is no exception here.
Another post presents a tool able to add conditional (“soft” &shy;) breaks to the (markdown) texts and (html) layouts or to remove them.
In this respect that is no (third) Jekyll trick, but the appropriate use of a tool in the site’s development and deployment.