technical aspects

This website is a repository of writing. Its job is to hold articles that speed up technical tasks: guides, specifications, process notes, checklists and short papers. A task that is written down well once can be done again by following the page, instead of being explained again every time.

1. Plain pages, nothing to build

Every article is one plain html file. There is no framework, no database and no build step: the files in the repository are exactly what the reader gets. The site is served by GitHub Pages straight from the repository, so publishing an article means committing the file and pushing it. Every change to the writing is kept in the git history.

2. Writing apart from code

The look of every page lives in one stylesheet, global.css. The parts every page shares, the menu, the footer and the side box, are separate files that each page loads when it opens. An article file holds only its own words. This is the point of the repository as a writing technique: the writer works on text without touching code, and a change of look never touches the articles.

3. Written once, shown anywhere

The articles carry no brand, so the same writing can serve many websites and many identities. Another website can show an article in three ways: link to it, copy its text block into its own page, or embed the whole page with an iframe: 

<iframe src="https://pubs.fndt.xyz/contents/page-00-00-example.html"
        width="100%" height="800" style="border:0"></iframe>

At the bottom of each article sits a second breadcrumb, switched off by default. It records where the article lives on the website that shows it, in the form site > category > page, so a reader can find the way back.

4. Finding an article

The top breadcrumb shows where an article sits here: pubs > category > page. Articles have no categories yet, so all of them are listed under all pages. The menu keeps the three links (home, pages, about), each ready to take a dropdown once categories exist, and the round button in the footer opens the same links for a reader who got lost.

5. Adding an article

  • copy contents/page-00-00-example.html and give it a new name,
  • write the title, the breadcrumb and the text,
  • add a link to it on all-pages.html,
  • commit and push. The page is live within a minute or two.

6. License

Code is under GPL-3.0 and the writing under CC BY-SA 4.0: anyone may share, adapt and republish both, with credit and under the same terms. See the license page.