(we are switching to a new theme, don't worry if things look different for a while!)

Site Navigation

Home
Search
All Pages
Recent Changes

Plans

Massive Wiki Roadmap
Pier2Pier
Massive Wiki Builder redesign

For Testing

wiki link test page
Mistletoe parser test page
Mistletoe & the ampersand story

For Fun

The Walrus

Edit This Page Clicking 'Edit This Page' opens this page on github.com. You can edit, and save changes, if you are a contributor to the repository. Close the edit page to return to this one.


Tech Note - Permanent Versions

last edit: 2022-12-07, Pete document status: draft, would like to expand the bullet sections to prose

Use Case and Overview

Wikis and their pages are meant to be edited and evolve over time. However, sometimes we wish to publish a page to the larger web in a way that is fixed and unchanging.

From the wiki side, wiki authors want to present the page as it was on the date of publication, even though the original page may change or be deleted as its home wiki changes.

From the web side, people who want to link to the wiki page from their web pages want to know that their future readers will find the same page content as when the link was originally created.

In terms of longevity, we wish for "permanent" versions to be findable, linkable, and readable in both the near term, and the far future: decades, centuries, millennia from present -- in other words, practically forever.

To satisfy these needs, we introduce the "permanent versions" pattern.

"Permanent Versions" folder

To implement permanent versions, create a top-level folder called "permanent versions". Change the case and separator character as appropriate for your wiki. Translate "permanent versions" to your home language as appropriate.

File Formats

For each published page, choose whether you want to publish the permanent version in HTML, Markdown, or even another format such as plain text. For the sake of simplicity and longevity, it is recommended to choose just one publication format for each page rather than presenting, for example, a Markdown page together with its HTML rendering as two separate files.

HTML will usually be the preferred format for publication to the HTML web.

Non-content Sections

Styling and site navigation can be rendered in the HTML version, although any non-content additions should be simple and it easily separable from the main page content -- perhaps even more so than in the usual rendered parts of the wiki.

Above the content, there should be a link to another page in the wiki about the permanent versions pattern, which explains that pages in the permanent versions folder have been frozen and published, and can be relied to not to change, even though they are presented within a wiki where other pages do change. Readers should be encouraged to use the title and body of the frozen page to search for updated versions in the rest of the wiki.

Content Hash in Filenames

To demonstrate and confirm that the page content is unchanged, it is recommended that the filename of the published page (and therefore, the resulting URL when posted to the web) be constructed with a content hash such as SHA-256. The hash can be computed over the whole published page, or just the page content. If computed over just the page content, there should be obvious markers in the page where the hashed content begins and ends. Note that automated hash confirmations will be somewhat easier if the whole page is hashed, rather than just the content.

Do Not Edit Permanent Versions

It is recommended that published pages not be edited. If they need to be changed or removed, the content can be removed and replaced with a short message that links to a revised page in the permanent versions folder, or a message that says that the published page has been deleted.

The message should be obviously not the intended content, and of course, it will fail a hash confirmation calculation.

Other Names Considered

Content Hash in Filename

Implementations

More information about using Massive Wiki Builder to generate a permanent version of a particular file will go here.

Discussion

WLA (2022-12-11): created an airtable for constructing Permanent Versions property metrics: https://airtable.com/appQ9KYTm2YxgCR2A/tblpTrYtVSqa7p5Xl/viwyiBVcKmR1HlBdc?blocks=hide


Pages that link to this page