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

Even Scalzi noticed this was an issue when his favourite corporate social media ran into problems in November 2022!

Useful Tools

Workflow 1.6.5 on 30 June 2024

Reworked some styles so that on narrow screens, the images with four donation links would not force the page width wider than the screen width causing pink background to appear.

    /* Allow images to wrap on narrow screns */
row-of-images {
  display: flex;
  flex-wrap: wrap;
}

Workflow 1.6.4 on 17 January 2024

After reading A Short History of Bi-Directional Links by Maggie Appleton, added WebMention to the template and look into linkback. This is a static site, so trackbacks would have to be added by hand. This would still be better than searching the Ahrefs Backlink Checker every so often! The terms IndieWeb and Digital Garden are a good match for my goals with this site.

Experimentally switched site search from DDG to searchmysite. The old code was:

    <form method="get" id="search" action="https://duckduckgo.com/">
    <input type="hidden" name="sites" value="ageofdatini.info">
    <input class="search" type="text" name="q" maxlength="300" placeholder="Search">
    <input type="submit" value="Search">
    </form>

If I typed "sword" into the search box, that sent queries to https://duckduckgo.com/?sites=ageofdatini.info&q=sword. After a chat with M.L. at searchmysite I use the following code:

    <form method="get" id="searchForm" action="https://searchmysite.net/search/">
    <input type="hidden" name="domain" value="ageofdatini.info">
    <input class="search" type="text" name="q" maxlength="300" placeholder="Search" title="Search Box" aria-labelledby="searchButton">
    <input type="submit" id="searchButton" value="Search"  title="Search Button">
    </form>

If I typed "sword" into the search box, that sent queries to https://searchmysite.net/search/?domain=ageofdatini.info&q=sword.

back to start of workflow 1.6.4 ↩︎

Workflow 1.6.3 on 9 January 2024

Worked through some issues with classes, IDs, and tags lost in pandoc conversion (my install turned out to be out of date), added a list of manipuli to the sidebar, and adjusted the styling. In particular, added some padding to .codesnippet so that the pale text does not run up against the edge of the dark background, and used a CSS descendant selector and CSS pseudoclass to automatically set the text colour in the left column of .parallelText tables. Previously I had to manually apply a span class="notEnglish" to each td in the left column.

table.parallelText tbody tr td:first-child {color: color:#330000}

Added a computing manipulus for this page and an unpublished page on web design principles. Added the snippet --from=html+raw_html to generate-page.sh to reduce the amount of conversion.

I previously discussed attempts to create a two-column layout under workflow 1.5.3.

Workflow 1.6.2 on 7 January 2024

Created a responsive two-column layout. The files needed to generate a page at ageofdatini.com/foo.html are:

  • generate-page.sh (this bash script needs execute permission granted with chmod)
  • aod-template.html5
  • styles.html
  • blogroll.html
  • whats-new.html
  • foo.html
  • foo.yaml

Created a test page at test/model-page.html to demonstrate markup and give a quick visual check that all is well. On this version, parallel-text tables with a 'not English' column do not display correctly. Therefore this workflow has only been applied to index.html and essays/how-do-i-make-this-site.html. Adding the test folder raised the issue discussed in workflow 1.5.2, in that until I created a site/test folder on my machine, generate-page.sh failed.

Workflow 1.6.1 on 5 January 2024

Applied the 'facts should have one canonical location" principle to generate a "What's New?" box and a blogroll box from dedicated files whats-new.html and blogroll.html. To do this I had to snip lines out of whats-new.html with shell commands in generate-page.sh and create a Pandoc partial containing them. Previously, I had to manually copy and paste lines from whats-new.html into index.html. Now generate-page.sh contains the following:

# Create a file with the 10 most recent entries in whats-new.html, which should begin with an unordered list

head -n 11 whats-new.html > wn10.txt
echo "</ul>" >> wn10.txt # append a closing tag to the list
...

And aod-template.html5 contains the following:

This is an example of a snippet of executable code which should look like it came from a text editor or IDE.

<div>
  <div id="blogroll">
    <h2>Blogroll</h1>
    $blogroll.html()$
    <p>For more blogs see <a href="https://www.ageofdatini.info/bibliotheca/useful-websites.html">Useful Websites</a></p>
  </div> <!-- #blogroll -->

  <div id="whatsNew"> <!-- first 10 entries from whats-new.html -->
    <h2>What's New?</h1>

    $wn10.txt()$
    
    <p>For older changes see the <a href="https://ageofdatini.info/whats-new.html" class="uri">What's New?</a> page</p>

  </div> <!-- #whatsNew -->
</div>

whats-new.html still needs to be manually updated since not every upload is worth recording there and judgement is needed whether a particular upload is added, updated, ported, or launched. And the list on a page will only be updated when that page is generated and uploaded.

Workflow 1.6 on 4 January 2024

Edited generate-page.sh, styles.html, and aod-template.html5 to create a skeleton Blogroll and What's New at the bottom of the page. In the near future I will use this as a base to implement a responsive multi-column layout.

Workflow 1.5.6 on 15 September 2023

Edited styles.css and aod-template.html5 per the Web Accessibility Validation Tool to increase contrast between links and header/footer background, add a form label to the search form and search button.

Workflow 1.5.5 on 31 August 2023

Forgot to add that its sometimes necessary to install the curl shell command to get generate-page.sh to run on some shells and Unix distros. So the procedure to create or update a page called https://ageofdatini.info/pageName.html on a new machine is:

  1. Copy over the ageOfDatini folder
  2. Install necessary shell commands such as curl
  3. Enable execution of ageOfDatini/generate-page.sh with chmod 700 generate-page.sh (text of the script in workflow 1.3)
  4. Create pageName.html and pageName.yaml
  5. Copy any media files on the page onto the web server
  6. In a Unix terminal, run ./generate-page.sh pageName.html

And a model YAML file is:

---
title: How Do I Make This Site?
page title: Age of Datini
author: S. Manning
keywords: web coding, web development, website building, pandoc
dateCreated: 2021-04-04
category: essays
manipuli: []
lang: en
---

To upload a specific file such as an image foo.jpg to the web server:

  1. In Files tool on Linux connect to ftp://ssl01.alldomains.hosting/
  2. Enter Username: ageofdatin.info and password: notMyRealPassword and click connect
  3. Navigate to the /www folder
  4. If you copy foo.jpg to the www/foo.jpg folder, it will be served from the URL https://ageofdatini.info/foo.jpg

Workflow 1.5.4 on 7 March 2023

From Pandoc maintainer John MacFarlane, if I want the for() loop that generates links to the manipuli not to run, set "manipuli: []" rather than "manipuli: " (not including a line for that variable in the YAML file also works). Markdown says that [] is an empty sequence but does not seem to define empty sequence.

Workflow 1.5.3 on 15 December 2022

Experimented with possibilities to create a sidebar, but no good solution so far. CSS flexbox layouts seems to have trouble creating columns which span the header, the main, and the footer. HTML 5 has a lot of new sematic elements such as aside and article as alternatives to a sea of div elements! See CSS FLexbox Responsive for an example of responsible three-column layout. The 'web page template' at https://www.w3schools.com/css/css_rwd_templates.asp might be adaptable. A rule of thumb for 'small devices' seems to be 768 px wide or less. Added a line to create links to any manipuli which a page belongs to.

Workflow 1.5.2 on 7 December 2022

Discovered one quirk of the current workflow while experimenting with a new folder called Manipuli: if any of the necessary folders does not exist on my machine, my machine/site or the web server, the process will fail. This is only an issue when adding new folders.

Workflow 1.5.1 on 20 November 2022

Added a new logo for ko-fi to the template.

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, ko-fi or Liberapay.

created and copyrighted on 2021-04-04 by S. Manning ~ last updated 2026-01-30

Powered by https://searchmysite.net/

This site accepts WebMentions

Blogroll

For more blogs see Useful Websites

What's New?

For older changes see the What's New? page

Manipuli

A complete list of collections are on the Manipuli page