title	cuid	trls	lang
Website Publication Files	26e4-a0	nl	en

How I create web pages from selected files from this repository, with private and public editions.

Quickstart

Prerequisites: install node and git; clone the source with git clone https://git.surfacemarkup.net/hans/ad_pubfiles.

0. In this repository, npm install dependencies, including Web Origami. The following instructions assume you also have installed the ori command with npm install -g @weborigami/origami. If not, replace ori in commands below with npx @weborigami/origami.

1. link or copy README.md to the parent directory of this repository, with the name ad_pubfiles_pub.ori.md. Now you have input for testing and development, since the ori template files look in the parent directory for files with this pattern. Optionally add more files with the pattern: [a-p]+_title[_pub-other-tags][.ori].md. That is:

• they MUST start with a sequence of characters a-p,
• followed by an underscore,
• followed by a title which does not contain an underscore,
• followed optionally by an underscore and one or more tags separated by hyphens. For testing purposes, only the pub tag is relevant.
• followed by the filetype extension .md. If you want to use Origami expressions in the file, use .ori.md.

The reason for this setup step is that on my machine, the parent directory contains my personal wiki. So I can't share the input with you directly. The filename pattern above is used for the process of selecting which files to include in the build. The figure below shows this arrangement.

2. Use the following commands to achieve the desired output.

• in private mode: ori "serve watch ., =debug ./site.ori('all')"
• in public mode: ori "serve watch ., =debug ./site.ori()"

site.ori only exposes the final rendering step from pipeline.ori. Therefore:

• To serve the pipeline with all the processing steps available for inspection, replace site.ori with pipeline.ori in the commands above.

How the site generator files relate to the content

Markup Language

I have developed a text markup format which suits my needs better than Markdown. The parser works and I can render HTML with it, but the feature set is still very limited. For example, I can only render single works in italic. That might seem like an odd sort of limitation, but it's because I've started from somewhat different first principles than the assumptions the HTML/Markdown worfklow is based on. As we all know, the last 10% takes the most work. So for now, I'm formatting the source files in Markdown.

Markup-taal

Ik heb een formaat ontwikkeld voor tekst die beter bij mijn doelen past dan Markdown. Het werkt, en ik kan er HTML mee genereren, maar er is nog een heleboel dat het nog niet kan. Omdat de laatste 10% altijd het meeste werk is, gebruik ik voor nu Markdown.

Changes and Updates

This section describes the idea behind the Changelog.

I've decoupled changes to the infrastructure from changes to the content of the site. I've inserted myself as an editor of the algorithmic file diffs. I review which files have changed between builds of the site, and write a changelog entry explaining what has changed in a way that's meaningful to readers.

The changelog is the 'subscription' mechanism for the site. Instead of a blog section where I write time-bound articles, I write smaller release notes where I draw attention to changes to the 'evergreen' pages making up the rest of the site. This way I can notify readers easily of both new content as well as revisions and expansions to existing content. In order to keep track of these changes, I need an easy way of seeing what has

In previous experiments, I put the build output in a separate git repository, then included the output of the git diff command in the source repository. It was a

I'm concerned primarily with changes to the output of the site. That means I can freely work on drafts as long as those files are not being selected, for the final public build by the pub tag.

Web Origami makes it easy to see which files have changed, with the Dev.changes builtin. You pass it the previous build of the site, and the output of the build script, and it reports files modified, added, or removed. What's nice about this is that you can get a summary of changes without writing the new build to disk. However, the Dev.changes builtin can't report detailed differences within files. So when composing the changelog entries I do write the new version to disk so I can use a text diffing tool like the graphical meld or the command-line diff for detailed comparisons.

Example

As I'm writing this, The output of the Dev.changes command looks like this:

$ ori 'changes build-26gb-a3/, site.ori()'
changelog.json: changed
changelog.rss: changed
changelog: changed
index.html: changed
pubfiles: changed

index.html might be expected to change because it gets summaries of all pages. My index.html really is an index. pubfiles is expected to change — that's this file. But why have all the changelog files changed, since I haven't published a new release yet? To see this, I'll build the site to a new directory, and then inspect a diff of the actual file contents.

$ ori 'copy site.ori(), clear files:build-26gc-a0'

$ diff build-26gb-a3/changelog/index.html build-26gc-a0/changelog/index.html

14a15,16
>   <!--summary-start-->
>

17c19
<   <!--summary-above-->
---
>   <!--summary-end-->

Ah, I changed the format of the comments by which I select summary text for the index. That's an infrastructural change. I'll either ignore it, or describe that in a separate section. Further inspection of the diffs shows that I have the following logical changesets to document:

• Added: this section 'Changes and Updates'
• Infra:
  • added highlight-js stylesheet (git commit templates,css: add highlight-js stylesheet. mdHtml already adds highlight.js tags to code blocks. · be6ea7b34e
  • started using a pair of comments to delineate page summaries, instead of just <!--summary-above-->, so that the summary doesn't have to the be first text in the file.

Future Work

What I want to do is create separate sub-feeds for additions, major revisions, minor edits, and infrastructural changes:

• additions: significant new content added, like new files or a whole new section (like this one)
• major revisions: changes to existing content which alters the meaning of what is written
• minor edits: fixing typos or turns of phrase.
• infrastructure: alterations to the look or behavior of the site as a result of changes to the code.

I'm pretty sure I'll be able to parse the changelog.md file further to create new feeds with only the relevant subheadings for each changelog entry. This way, people can subscribe to new content and major revisions without being bothered by minor edits.

I suppose I should include, somewhere in the output, which 'infrastructure' version was used to build the site, identified by a commit hash.

I also want to try serving the history of the site. The ingredients that are playing around in my head:

• rsync build-vY --link-dest=vX server:/vY will hard link unchanged files to the previous build directory when copying to the server. This means many versions can be stored with greatly reduced disk space.
• the web server would map / to a directory latest which is a symlink to the latest build. Other builds are available under a version prefixed path, e.g. https://hansfast.net/v26cg-a0/pubfiles.
• a wrapper script would take care of creating the new version directories and updating which one latest points to.
• the ori templates would add links to the next and previous versions of the current file.
• should the next/prev links be baked into each build, or should the server keep a list and resolve generic /next, /prev requests based on a query parameter for the current version?

Source files

The scripts and templates used to build this site are available here.

—private-below—

EXCEPT NOT REALLY! In this case, because this file is hardlinked to README.md inside a publicised git repository. You have been warned!

Internal Links

Internal links need to be absolute from the root of the directory. This SHOULD be fixed in a future version.

Web Origami, Public and Private Site Versions

I want to make only select files public. Files whose name contains the tag pub should be included in the public build. The public build should be the default. To include all files, pass 'all' to the site.ori file. That sort of reduces the risk of accidentally publishing private files.

Organisation

${ada_pubfiles-worklog.md/}