What shows when something is missing. A static (22 passages, no note) site (note: Site) has no support desk (4 passages, no note): the page is the only recourse. It names the cause in plain words, says what stays reachable despite the lack (4 passages, no note), and offers at least two ways out; no partial lack hides the rest of the page, and the navigation is always kept. A notice (12 passages, no note) is allowed on these states (36 passages, no note) alone, nowhere else in the site.
The rule (note: Rule) common to every one of them: name the cause in everyday words, never a code alone, the code coming second when there is one; say what remains (6 passages, no note) reachable; offer two exits at least, one of them assuming nothing; keep the navigation, never a bare page.
Today
Page not found. The build (note: Build) writes 404.html at the root of the site, the page GitHub (10 passages, no note) Pages and GitLab Pages serve for any missing address (56 passages, no note) under it, with the bar (28 passages, no note) and the footer (19 passages, no note) of every page. The eyebrow reads "Page not found", the title "This address matches (note: Occurrence) no page of the last publication (40 passages, no note).", the sentence (25 passages, no note) under it names the likely causes and what remains: "The file may have been renamed or moved (6 passages, no note), or its word fell (3 passages, no note) under the publication threshold (note: Publication threshold). The content (43 passages, no note) stays in the repository (note: Knowledge repository) and its text stays searchable (4 passages, no note)." An identifier (note: Identifier) derives from the path, so renaming a file breaks the links (note: Link) already shared; a word that fell under the threshold lost its page, its occurrences staying (5 passages, no note) in the index (note: Alphabetical index). Two exits close the page, "Search “publication treshold”", the search on the last segment (11 passages, no note) of the address, and "Browse (7 passages, no note) the spaces (note: Space)". Between the sentence and the exits, "Nearby addresses" lists the three pages at most whose address stands closest, each with its title and its address: the name of the page, its last segment, compared by edit distance (6 passages, no note) with the last segment of the address asked for, so that a renamed file stands a character (16 passages, no note) away and a moved file none, the nearest folder first among namesakes, none proposed (4 passages, no note) beyond half the length of the name. The table (40 passages, no note) of the pages is written at publication, in the entity table (5 passages, no note) of the search index; the comparison (15 passages, no note) runs in the browser (31 passages, no note), which alone knows the address asked for. The host (8 passages, no note) serves this page at any address, so its links cannot be relative: its head names its own address as a base (19 passages, no note), from the path of site.url in the configuration (note: Configuration), the root of the host without it. Without JavaScript the nearby addresses stay hidden and the search exit reads "Search the documentation (12 passages, no note)": the cause, what remains and the two exits stand in the served HTML.
Zero (3 passages, no note) results (48 passages, no note). The search tells two causes apart. The filters left every match out: the notice reads "No result for “staleness” with the filter Screen." (the filters listed when several), the sentence "The word exists in the documentation, but on none of the pages the filter keeps.", and one exit per filter, "Remove the filter “Screen”", with the count of results that lifting it alone gives back. No file uses the word: the notice reads "No result for “thresold”", the sentence "No file uses this word.", the closest form of the dictionary stands beside, and a line explains that "The search matches the start of words: a typo gives zero results and no suggestion.", the page saying it in one line rather than staying silent (3 passages, no note). Either way "See the page of the word", drawn (23 passages, no note) dashed (13 passages, no note), leads to the page whose title or alias (note: Alias) is the query (note: Query), with its occurrences or its citations (note: Mention), when the corpus (note: Corpus) has one.
Preview (note: Preview) unavailable. The most frequent lack, and the least serious. A document page whose conversion failed, the finding (note: Finding) conversion failed recorded for its path, shows in place of its rendering the notice "The preview of this document (note: Document) could not be generated." with, when its text was read all the same, "The text was extracted (31 passages, no note) all the same: it is indexed (7 passages, no note), cited (30 passages, no note) on the other pages, and readable below.", else "Its text could not be extracted either: the original stays downloadable, and the note (note: Note) that describes it stands among its files."; two exits, "Download (30 passages, no note) the original" and "Why this failure (4 passages, no note)?", which unfolds the cause as the build worded it, "conversion (note: Conversion) of decks (note: Deck)/scan.pptx failed: timed out after 120 s", and the check identifier (4 passages, no note) after it; then the extracted text (note: Extracted text) position by position (3 passages, no note) under "Extracted text — 24 pages · indexed and searchable". The panel (97 passages, no note) adds "State of the representations (note: Representation)": .pptx available, .pdf preview failed, the word written and not only coloured, text extracted or missing, with the note that the same finding stands in the publication report (3 passages, no note) and in the linter (note: Linter) output: the failure is reported to whoever can fix it. A document without a preview and without a finding shows nothing of it.
Contract unreachable (3 passages, no note). The page of an interface (21 passages, no note) whose declared contract (note: Contract) the build could not read, the finding unreachable contract recorded for it, keeps the generic layout of the API page and says so under its title with the same notice: "The contract of this interface could not be read.", "The note stands on its own meanwhile: its text and the operations (note: Operation) it describes are indexed and cited like any page.", the exit "Open the contract address" when the declared location is one, and "Why this failure?" unfolding the finding. The notice is one component (46 passages, no note), the only banner (3 passages, no note) of the site, which the failed conversion shares.
Ageing publication. If a publication fails, nothing is deployed: the former site stays online, unchanged and silent, and can only tell its own age (4 passages, no note). Its publication date (44 passages, no note) is written in it, and the expected cadence is declared in the configuration as site.publish_every_days; past three times that cadence, every page shows between the bar and its content the notice "Notice · This version was published 12 days ago. Publications are declared daily in the configuration. A recent (3 passages, no note) change of the repositories may therefore be missing here. See the sources (note: Source) and their versions or consult the repositories directly.", the first exit leading to the spaces, the second to the repository of a source. It appears by itself, without a server or a request (31 passages, no note), the days counted in the browser; a button closes it, and it comes back only after a later publication grows old in its turn. Without JavaScript it stays hidden: no page knows the day it is read. What the site cannot know: that a publication failed, since it wrote nothing; the pipeline (note: Pipeline) alerts (6 passages, no note) the team, not the site the reader (note: Reader), which is why the linter runs before the build.
Two cases remain to frame (5 passages, no note): a page whose file is empty, and a repository that became unreachable (7 passages, no note), whose pages vanish while the links pointing (3 passages, no note) at them do not know it.
Objects
Actions
- Search the last segment of a missing address → search
- Browse the spaces → spaces
- Download the original of a document whose conversion (3 passages, no note) failed → document page