Fashion in the Age of Datini

How Do I Make This Site?

People don't talk much about how they make their websites any more (although they often talk about their accounts on corporate social media). I think its wise to push back against this deskilling and against the unstated premise that if running your own site is for you then you already know how (or that to build your own website you need to understand anything more than HTML and CSS and how to edit plain text and move files between folders). And its handy to have a record of my workflow for when I return to the site after a delay.

To see my latest workflow, click here

Inspirational Reading

Useful Tools

Workflow 1.5 on 18 May 2022

After a chat with Alex Schroeder @kensanata@octodon.social and others, added a line to upload the generated file automatically:

echo Content $1 plus metadata $metadataFile makes $targetFile

pandoc $1 --metadata-file=$metadataFile -o $targetFile \
--template=aod-template.html5 \
--variable=dateUpdated:$dateUpdated

# Upload the new file with curl and FTP
# N.B. password may be rejected if it contains certain characters other than letters and numbers

curl --user ageofdatini.info:notMyRealPassword \
-T $targetFile \
ftp://ssl01.alldomains.hosting/www/$dirPath/

echo Uploaded to /www/$targetFile

Uploaded this page using the new script like a boss! You can learn about curl through the man page or https://everything.curl.dev/ftp and https://sylvaindurand.org/deploying-a-static-website-with-ftp/

Images etc. for the generated page still have to be copied over by hand.

back to start of workflow 1.5 ↩︎

Workflow 1.4 on 29 May 2021

Added donation links to the template. To do this, I needed to find small images of the logo of various donation services. I found them in the followng places:

Knowing what pages with 'sets of official logos' are called is half the battle!

back to start of workflow 1.4 ↩︎

Workflow 1.3 on 7 April 2021

Get rid of markdown and generate HTML from a HTML code fragment. Unfortunately, Pandoc does not seem to be able to handle html fragments with a metadata block in the same file so I have to move that into a separate file. Dump output in a dedicated folder.

~/Documents/Publications/ageOfDatini$ pandoc how-do-i-make-this-site.html --metadata-file=how-do-i-make-this-site.yaml -o site/how-do-i-make-this-site.html --template=templates/tt2.html5 --variable=dateUpdated:$( stat -c %y how-do-i-make-this-site.html | cut -f 1 -d ' ' )

This can be turned into a simple shell script in the same way as workflow 1.2 (gnu.org still has good manuals). This creates the site's proper directory structure in the site folder so its contents can be copied directly onto the server.

#!/bin/bash

# if $1=./foo.html, takes $1 
# and ./foo.yaml 
# and ./styles.html
# and ./aod-template.html5 
# to generate ./site/foo.html

MY_PATH="$( pwd )"

fullpath=$1
dirPath=$( dirname $1 )
sourceFile=$( basename $1 )
metadataFile=$( echo "$fullpath" | cut -f 1 -d '.' )'.yaml'
targetFile='site/'$dirPath'/'$sourceFile

# Linux: Using file system information to get creation and modification date.
# Warning: This may yield faulty data if you use git and multiple computers.
dateUpdated=$( stat -c %y $fullpath | cut -f 1 -d ' ' )

echo Content $1 plus metadata $metadataFile makes $targetFile

pandoc $1 --metadata-file=$metadataFile -o $targetFile \
--template=aod-template.html5 \
--variable=dateUpdated:$dateUpdated

exit 0

Run the script as follows then copy the output files from the /site folder onto the /www folder of the server over FTP:

~/Documents/Publications/ageOfDatini$ ./generate-page.sh bibliotheca/main-bibliography.html

This still has some side effects, probably unavoidable ones, because pandoc processes files twice (input to intermediate format to output) rather than once. For example, the following fragment of input:

    
<figure>
    <a href="/images/2021/04/acme-widgets.jpg">
    <img src="/images/2021/04/acme-widgets.jpg" alt="a mysterious machine sticking out of a cardboard shipping box" />
    <figcaption aria-hidden="true">One of this proud company's most famous products, the type 37 widget ...</figcaption>
    </a>
</figure>
    

become like so in the output:

    
<figure>
<img src="/images/2021/04/acme-widgets.jpg" alt="One of this proud company's most famous products, the type 37 widget ..." /><figcaption aria-hidden="true">One of this proud company's most famous products, the type 37 widget ...</figcaption>
</figure>

The <a> tag and the contents of the alt attribute are thrown away without my consent (good alt text is not the same as a good caption! The caption tells you how to interpret the picture, the alt text tells you what the picture would be if you could see it). Apparently "templating engine" is a keyword but I am trying to understand which are run-once on the server-side and which run-many-times or client-side. As of 14 April 2021 I do not understand two relevant GitHub issues but my head is not clear https://github.com/jgm/pandoc/pull/6495 and https://github.com/jgm/pandoc/issues/6782

back to start of workflow 1.3 ↩︎

Workflow 1.2 on 6 April 2021

Create a file process-one-md-file.sh which takes ./$1 (the first argument passed to the script) and ./template.html5 and produces ./$1.html (I would quote it here but the Markdown → HTML conversion mangles it hopelessly).

Enable execution of that file as a shell script.

chmod 700 process-one-md-file.sh

~/Documents/Publications/sampleWebsite$ ./process-one-md-file.sh how-do-i-make-this-site.md Processing: how-do-i-make-this-site.md 

Problems: only one file at a time, can only process files in the same folder. There are still issues where formatting something as good HTML makes Pandoc throw up, and formatting it as Pandoc creates unnecessary <pre> or <p> tags. Pandoc even reads a pandoc shell command with -- for 'verbose options' and replaces them with one big dash so that the output is no longer a valid command! Output is in same folder as input which makes it hard to copy just the output onto the server in a single step.

back to start of workflow 1.2 ↩︎

Workflow 1.1 on 6 April 2021

~/Documents/Publications/sampleWebsite$ pandoc how-do-i-make-this-site.md -s -o how-do-i-make-this-site.html -–template=templates/tt2.html5 –variable=dateUpdated:$( stat -c %y how-do-i-make-this-site.md | cut -f 1 -d ’ ’ ) -–from markdown-markdown_in_html_blocks

Added --from, corrected stat command to point to the file being compiled not index.md

back to start of workflow 1.1 ↩︎

Workflow 1.0 on 5 April 2021

Model: Roman Gerber, "Creating Static Websites with Pandoc" https://www.romangeber.com/static_websites_with_pandoc/

~/Documents/Publications/sampleWebsite$ pandoc paintings-and-sculptures.md -s -o paintings-and-sculptures.html –-template=templates/tt2.html5 -–variable=dateUpdated:$( stat -c %y index.md | cut -f 1 -d ’ ’ )

Copy HTML files onto the server by hand with ftp using the file browser on my Linux box.

Problems: bug in processing of HTML tables with a <th> element, stat shell command does not have the most friendly output format.

back to start of workflow 1.0 ↩︎

This site is free, but its not costless. Help keep it going with a donation on paypal.me, Patreon, or Liberapay.