docs: make the front page a landing page - #490
Merged
Merged
Conversation
lens0021
force-pushed
the
claude/landing-page
branch
2 times, most recently
from
August 20, 2026 16:20
d2bc007 to
0b76a8a
Compare
lens0021
changed the title
lens0021
force-pushed
the
claude/landing-page
branch
from
August 20, 2026 17:31
fe73403 to
01d9774
Compare
index was a good essay: five paragraphs and two bullet lists, read top to bottom or not at all. Someone arriving wants to know what this is, whether it fits, and where to start, and had to read for it. Same content, same words, arranged so it can be scanned: the opening paragraph as a lede at a controlled measure; the paragraph about when to reach for wikven behind the page's one accent rule, because that is the one a reader is actually weighing the tool against; three cards for the first three steps of the documentation; the install sentence demoted to a caption under them, since it names the three install shapes the cards do not; supported and unsupported side by side as the one comparison they are; and the closing paragraph as a coda under a hairline. Not a single translation unit changed. Every <!--T:n--> keeps its marker and its exact text, the layout divs sit outside the translate tags the way Getting Started interleaves its tabber, and docs/index/ko.wikitext is untouched and needs no restamp. The card labels come from the targets' own translated titles through Template:prevnext/label, the same lookup the bottom-of-page navigation uses and for the same reason. The stylesheet reads the skin's Codex tokens and defines none, so the page follows the reader's theme in all three skins. It cannot define one: TemplateStyles drops a custom-property declaration, silently. Widths come from repeat( auto-fit, minmax() ) rather than media queries, because the content column is a different width in each skin and a reader preference in Vector besides, so the viewport says nothing useful about the space a band has. No hero band: the skin already draws the H1 and the language bar, and a second header underneath would fight it. No filled call-to-action button either -- a fill needs an inverted text colour that flips with the theme, and with no way to define a token that would mean hard-coding one theme's pairing. Bordered cards read from tokens and cannot break.
The first pass laid the existing page out in bands and changed not a sentence of it, which left the front page reading as the first page of the documentation with a grid around it. A landing page has a different job: a reader who has just arrived wants to know what this is, see that it is small, and be pointed somewhere. So the page is written for that. The lede says what wikven is and ends on the thing worth saying -- nothing runs behind the published site. Under it are the three commands that show the whole tool, because for this kind of software the commands are the argument. Then the three route cards, unchanged. Then four things wikven can do, one sentence each, chosen for being worth choosing it over: templates and Lua, extensions and skins, search with nothing to query, many languages. Then one closing line on where it fits, keeping the Hugo and MkDocs comparison a reader weighing tools actually wants. What went: the paragraph restating the fit that the coda now carries in a sentence, the paragraph listing the three ways to install, which is what the Installation card is for, and the seven-item feature list, whose every entry was a link to a page already in the sidebar. The list of what a static export cannot do went to an appendix, Limitations, first in the References group. It is a fair question and the answer is not shameful, but it is not the answer a landing page should give first. The page is better as an appendix than it was as a column: each item now says what stands in for it -- the repository for history and editing, the Settings page for reading preferences, the browser for search, the About page for Special:Version -- which the landing page had room for only as one trailing sentence about two of them. Both pages are translated into Korean and stamped.
The last pass cut the words but kept the shape: bands of prose stacked down a column, which still read as a wiki main page. This is the layout the words were cut for. A hero -- a tagline set large, one sentence under it, a filled button to Getting Started and an outlined one to Installation. Then five short bands, each labelled rather than headed: the section titles are set as small caps labels instead of the ruled headings the skins draw, because five full-width rules down a short page read as five articles stacked up. How it works is the three commands. What you get is four cards, a title and one line each. Where it fits is three phrases. Then a closing line with the button again, and the fine print. The prose came down by about half again: the four feature cards were two or three sentences each and are one line each now, and everything that was a second way of saying something already said is gone. The page suppresses its table of contents. It has five headings and none of them is a section anybody navigates to, and the tagline is set like a heading precisely so it does not have to be one. One literal colour, on the filled button: a button carries its own background, so it cannot read --color-progressive, which night mode moves to a pale teal that white text sits on at 2.07:1. The brand teal holds white at 5.76:1 in both themes.
The first thing above the tagline was Translate's language bar, so the first choice the page offered a reader who had not yet been told what wikven is was which language not to read it in. <languages /> renders where it is put, so it is now the last thing on the page. Nothing is hidden and nothing is overridden: the bar is one tab stop from the end rather than one from the start, and every skin here carries a language control of its own for a reader who wants one sooner. Translate's "this page is a translated version" notice is still at the head and is not touched here, because this stylesheet cannot reach it: TemplateStyles prefixes every selector with .mw-parser-output, and that notice is written before the parser output rather than inside it. That one would have to be a page-scoped rule in MediaWiki:Common.css.
Four things, all visible in a screenshot of the built page. The four cards rendered three-up with the fourth orphaned on a row of its own, stretched. Four equal items in an uncapped repeat( auto-fit ) grid do that at every width that fits three, and which widths those are depends on the skin's root font size, so no minmax() tunes it out. The grid is capped at 48rem instead: three 16rem tracks with two 1.5rem gaps is 51rem, so three cannot happen. Two up on a column, one up on a phone, and both numbers in rem so a skin with a bigger base size scales the cap with the tracks. The card bodies were speckled with inline links -- six teal fragments scattered through grey prose in grey boxes, which is what a wiki paragraph looks like. One destination per card now, and it is the title. "Where it fits" was three phrases under three teal rules: a table header drawn over content with no columns in it, ragged because the phrases are different lengths, and the loudest marks on the page sitting above its least important band while the call to action sat quieter. It is one line of three phrases now, and the teal is on the buttons and the links. The measures were 30, 34, 40 and full-width, so the right margin stepped in and out four times down the page. Two measures now, 34rem to read and 48rem to look at. Four more things the render made obvious once those were fixed. The cards were a fill with no border, and --background-color-neutral- subtle against the night ground is about 1.1:1 -- the cards were not present at all in one of the two themes this site ships. The border is the card now and the fill is a bonus. The filled button was pinned to the brand teal in both themes, which measures 3.2:1 against the night ground: the page's most important element stopped being its loudest in half the sessions, beside links that had moved to cyan. MediaWiki:Common.css now carries an inverting --wikven-cta-* pair scoped to .rootpage-index, which TemplateStyles reads. 5.76:1 by day and 8.93:1 by night, for the text and for the button against the ground alike. The section labels were tracked-out caps, which is an eyebrow's device doing a heading's job in the page's quietest type -- and it only worked in Latin script, since text-transform does nothing to Hangul while the letter-spacing still loosens it. Sentence case at 1.375rem. The closing band was centred, rounded and grey on a page that is flush left everywhere else: the shape of a consent notice, and the third grey rounded rectangle in six bands. A rule and a size now, so the page's two rules both frame it.
The logo, the note icon and the README image were still drawn in #157f93, the teal #489 moved the brand off. So the mark sat above links and buttons in a teal 6.5 dE away from its own -- close enough to read as a mistake rather than as a second colour. They move rather than the token moving back, because the token cannot: #157f93 measures 4.44:1 on the #f8f9fa the skins use for a subtle background and 3.96:1 on #eaecf0, both under AA for text, which is what #489 was fixing. A logo is a graphic and needs 3:1, so #10707f costs it nothing -- 5.76:1 on white. logo.png had no vector to regenerate from and this container has no image library, so it was decoded, the 6913 pixels of exact brand teal remapped, and re-encoded. A few dozen antialiased edge pixels blend the old teal with what is under them and are left alone.
The landing page sets a tagline where a title would go, and the site name sat above it, so the first two lines of the page were the word Wikven and then a sentence about Wikven. MediaWiki's own way to do this is to blank MediaWiki:Mainpage-title and MediaWiki:Mainpage-title-loggedin. This site cannot use it: those messages are read only for the page Title::isMainPage() is true of, and MediaWiki:Mainpage here holds "Special:MyLanguage/index" rather than "index" so that every skin's logo follows the reader's language -- which, as Editing sidebar already documents, is what stops the wiki recognising the page as its main page. The logo behaviour is worth more than the seven lines this costs instead. So it is a rule in MediaWiki:Common.css, which is not sanitised; TemplateStyles could not do it, because it prefixes every selector with .mw-parser-output and the heading is outside the parser output. Scoped to rootpage-index so the translations are covered by the same rule. Clipped rather than display: none, so the heading stays in the accessibility tree and the page keeps its h1 for a reader who is not looking at it.
Two things the second render showed. The demo block came out in two nested boxes. SyntaxHighlight draws its own, and the border added here landed on .mw-highlight and on the pre inside it, so both were drawn. The border goes; only the margin was ever needed, and leaving the block its native box also keeps this out of the way of whatever the extension's own stylesheet does in night mode. "Where it fits" set its three phrases inline, so they broke wherever the line ran out: the middle one ended a line on "plain" and began the next with "HTML", with a middot between it and its own tail. inline-block wraps each phrase as a whole. The middle phrase was also the longest by far, which is what made the band ragged in the first place, so it says "An archived wiki" now and lets the fine print carry the rest.
The 48rem measure was on the bands, so it was on their rules too, and the hero's rule and the closing band's rule stopped well short of the column while the skin's own rules -- under the title, under the tabs, above the footer -- ran the whole width of it. Two rules ending in one place and three in another does not read as a narrower measure. It reads as the page having slipped to the left, which is what it looked like. The bands now run the full column and the measures are on what they hold: 34rem for the sentences, 54rem for the two objects that are looked at rather than read. The card grid keeps a cap because it needs one -- three tracks orphan the fourth card -- so its floor goes up with it, to 18rem, which still makes a third track impossible under the cap.
lens0021
force-pushed
the
claude/landing-page
branch
from
August 20, 2026 17:41
4491d43 to
d1e1bfc
Compare
lens0021
marked this pull request as ready for review
August 20, 2026 17:41
The two things the design review asked for that were still outstanding. The logo appears on this page only as header chrome, at a size that makes it a wayfinding icon rather than the product's mark -- and the tagline right under it is about baking, which is what the mark draws. It goes at the top of the hero, decorative: the link is off and alt is empty, because the page title says the name already and still says it to a screen reader. "How it works" showed what you type and then spent a sentence describing what you get. It shows both now, in two panes, and the sentence is down to the rule it was really there for. The dist/ pane is the root of a real build cut to the four entries that say what kind of thing it is: a page, a stylesheet, a script, and the search index. No arrow between the panes -- an arrow turns around for a right-to-left reader and says nothing to one who is not looking -- so the labels carry the direction. Two panes also means auto-fit can never leave an odd one out, which is the trouble the card grid above had to be capped to avoid.
The rule sat immediately after the syntax-highlight palette that #492 deletes, with no unchanged line between them, so the two branches could not both be merged without a conflict in a file neither of them really disagrees about. It goes to the foot of the file instead, beside the MobileFrontend footer rule -- the same kind of thing, one site's chrome tweak -- and the two changes no longer touch.
Same reason as the title rule, and this was the block actually causing the conflict: the token trio sat immediately after the last .mw-highlight declaration, inside the run of lines #492 deletes, so git had a deletion and an insertion with no unchanged line between them. Both landing-page blocks are at the foot of the file now, together, and the two branches merge without touching each other.
The panes had the cards' 18rem floor, which is about 41 monospace characters, and the echo in the left pane is 44. So the one command that matters most on the page was breaking across two lines, where it reads as two commands. 22rem fits it; below the width for two panes they stack and each gets the whole column.
Every skin puts the logo in its own header, a couple of hundred pixels above where this put a second copy of the same image, so the page opened on the same mark twice running. The header's copy is the one that belongs to the reader's navigation; this one was only decoration, and decoration that repeats itself is worse than none.
The rule went with the mark; its comment did not, so the file opened on a paragraph about an image the page no longer has, sitting above the hero's own comment.
The band was meant to read as a transform and read as two code blocks that happened to be adjacent, because that is what it was: lang="text" produces a .mw-highlight box with no tokens in it, so the markup was saying "here are two code blocks" and no styling of the wrapper was ever going to say anything else. The output is not code. It is a directory, so it is written as ordinary markup and drawn with borders on zero-size boxes, sitting on the page ground with nothing round it. Only the input is framed, and that asymmetry is the thing an arrow between two identical boxes could not do. The panes stack rather than sit side by side: the echo is 41 characters and half of 54rem does not hold it at every skin's code font size, so it was breaking one command across two lines. There is a direction cue now, above "You get", and the claim this file used to make against one was wrong on both counts. A triangle drawn from logical borders turns itself around for a right-to-left reader, and a content: "" pseudo-element is not in the accessibility tree at all, so saying nothing to a reader who is not looking is what it is for. The cards lose their boxes to the same end. Four boxes each holding a bold line and one sentence are mostly padding, and they were the same light grey bordered material as the demo, so the page's proof and its list of points were the same object twice. A rule on the leading edge does the work, and "framed" now means one thing on this page. Also: the rule the section states is above the demonstration rather than a footnote under it; section headings go to 1.75rem, because a teal card title at 1.125rem was out-shouting a near-black heading at 1.375rem; the tagline goes to 3.25rem and the hero gains a top margin and loses its rule, which was the third identical hairline in two hundred pixels; the focus ring is stated rather than left to the UA, which was drawing a dark ring on a light-teal button in night mode; the middot between the "where it fits" phrases stops being coloured by a border token; and the sentence saying what wikven is instead of moves out of the fine print, where it was set as a disclaimer below the last call to action, into the band that is about where wikven fits. doc.wikitext had drifted from the values it explains -- it still argued the two-up cap from 16rem tracks and a 48rem cap, when they are 18 and 54. The conclusion held; every number in it was wrong.
The cards' cap is argued from 18rem tracks, not the 16 it used to have, and the note about which properties can read a token -- everything the page draws comes out of a border or background colour, because a var() inside linear-gradient() is dropped silently -- was written for this file and did not land in it.
The last three passes were argued from screenshots and CI runs, a full round trip each. This one was drawn as a mock first, at the width the Citizen render actually gives the content, and agreed there; what follows is that mock in wikitext. The diagram is source in, one command, site out. Both sides are ordinary markup drawn with borders on zero-size boxes, with the command between them as the only filled object on the page besides the button, and an arrow either side of it. The three shell commands go: what is left is "wikven build", so the closing line is now one command rather than three. It never wraps -- an arrow pointing right means nothing once the parts are above one another, and there is no container query to ask with, so a narrow column scrolls the diagram in its own box. Files in the trees carry a type mark: two glyphs, a document and a folder, in five colours, with .wikitext in the brand teal so the source pane is one colour against a mixed output pane. They are SVG masks in MediaWiki:Common.css, not images and not a filter: an uploaded SVG is a fixed-colour picture that cannot follow the theme, and a filter could only invert or rotate the colours a file already has. The caret that blinks in the command is there too, because @Keyframes is not something the sanitised stylesheet can rely on. Both are scoped to rootpage-index. The spacing and the shape come from the page that was given as the reference. Its section unit is 4rem; bands here are 6rem apart, 7 around the diagram, cards 4rem apart with 2rem inside them, 7rem above the closing rule. Its feature cards are outlined boxes with a 1rem radius and no fill, which is what makes them read as roomy rather than as padded lozenges, so the cards and the diagram's panes are built that way too. Type goes up with it: headings to 2rem, card titles to 1.375, bodies and the lede to 1.125-1.25. Not taken from it: the warm near-black palette, because this site has its own teal and has to serve the reader's own light or night theme; the weight-100 body text, because the face here is whatever the skin sets and a missing weight is synthesised badly or ignored; and the stacked gradients on its hero, which would fight the theme rather than follow it. index/ko is retranslated for the three units that changed and restamped; StalenessComputer::analyze() reports every unit on both translated pages up to date.
It scrolled sideways instead, on the grounds that an arrow pointing right means nothing once the parts are above one another and there is no container query to ask the column's width with. The first half of that holds and the second was too strict: a viewport query cannot tell a wide column from a narrow one at a wide viewport, but it can tell that a narrow viewport has a narrow column, because a wide column cannot happen inside one. That is the only direction this needs. So below 46em the row becomes a column and the arrows turn to match. They are rebuilt rather than rotated -- they are made of borders, so pointing them down is a matter of which sides carry the colour and which carry the transparency, and a transform would be a second way of saying the same thing and one more property that could be dropped. The trees scroll inside their own pane as well, so a long file name is not clipped by the pane's corner radius on a phone.
Stacked, the two panes rendered as a pair of hairlines: the arrows and the command were there and the trees were not. flex-basis is measured along the main axis, and turning the row into a column turns the main axis from the inline one to the block one. The flex: 1 1 0 that makes the panes share the row therefore asked, once stacked, for panes nought pixels tall -- and the container's height comes from its content, so there was no free space for the grow to hand back and nothing to reopen them. They were left showing their own borders. Stacked, a pane is as tall as its tree: flex: 0 0 auto.
Three lines of the output tree are read off their extensions and the fourth is a product name. A reader who has not met Pagefind gets nothing from it, and the sentence that would explain it is two bands further down, on a card about search -- which is the wrong way round for a diagram that is supposed to stand on its own. So that one line says what it is, in the subtle colour, and the other three still say nothing because they do not need to.
The row carried min-inline-size: min-content, so it refused to be narrower than its own contents -- and its contents are two trees set nowrap, whose min-content is the longest file name in each. That put the row's floor at roughly the sum of two file names, two arrows, the command and four gaps, which was just inside the column until the gloss on the search index widened one of the names and tipped it over. The floor was never needed. Each pane has one of its own, and each tree scrolls inside its pane, so an over-long name moves the name rather than the diagram. The band keeps its own overflow as the backstop for a column too narrow even for the panes' floors.
Three phrases on one line under a 2rem heading is eleven words wearing a whole section's worth of structure. It was not a sentence and not a list, so it read as a caption that had lost its bullets -- which is what it looked like when it was three columns under three rules, and moving it onto one line changed the symptom rather than the cause. The three uses are the first thing the paragraph says now, and the band has the shape every other short band on the page has. No word of it changed; the arrangement did. Their three translation units are gone, folded into the one the paragraph already had, and removed from the Korean page so nothing is left orphaned. Also fixes a comment that had drifted a day behind the code: it still said the diagram never wraps and scrolls instead, which stopped being true when the row learned to stack below 46em. The overflow it describes is the backstop under that, not the plan.
"Bake a wiki into a website" names an existing wiki as the input, so it reads as a tool that converts one -- which is not what this is. The input is wikitext files you write; there is no running wiki on either side of the transform, and the diagram under the tagline says so in the next breath. One word fixes it. "Bake" stays: it is the project's own verb, the build job is called bake, and the logo is an oven.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The front page was the first page of the documentation: a lede, a paragraph on fit, a paragraph on the three ways to install, a seven-item list of supported features, a five-item list of unsupported ones, and a closing note. All of it true, none of it arranged for someone who has just arrived.
The early passes here are worth naming because each was half a job. The first laid the same sentences out in bands — the same page with a grid around it. The second cut the words but kept the shape. The third changed the layout, which is what the cutting had been for. After that the loop changed: the page was drawn as a mock at the width the content actually gets, agreed there, and only then written back into wikitext. Everything below that point was settled before it was built.
The page
src/in,$ wikven build,dist/out.The page suppresses its table of contents — none of its headings is a section anybody navigates to.
What went
The appendix.
Limitationsis a new page, first in the References group. What a static export cannot do is a fair question and the answer is not shameful, but it is not the answer a landing page should give first. The page is also better than the column it replaces: each item now says what stands in for it — the repository for editing and history, the Settings page for reading preferences, the browser for search, the About page forSpecial:Version— where the landing page had room for one trailing sentence about two of them.The diagram
It was two
<syntaxhighlight>blocks side by side and read as two code blocks that happened to be adjacent, which is what it was:lang="text"produces a.mw-highlightbox with no tokens in it, so no styling of the wrapper could have said anything else.Both sides are ordinary markup now, drawn with borders on zero-size boxes, with the command between them as the only filled object on the page besides the button — the only thing on the page that does something. Its caret blinks, and stops under
prefers-reduced-motion.Files carry a type mark: two glyphs, a document and a folder, in five colours, with
.wikitextin the brand teal so the source pane is one colour against a mixed output pane.pagefind/is the one line whose name is a product rather than a file type, so it says what it is; the other three are read off their extensions and say nothing.Below 46em the row stacks and the arrows turn to match. A viewport query is the wrong instrument for most of this stylesheet — the content column is a different width in each skin and the viewport does not say which — and the right one here, because a wide column cannot happen inside a narrow viewport. The arrows are rebuilt rather than rotated: they are borders, so pointing them down is a matter of which sides carry the colour and which carry the transparency.
What is in MediaWiki:Common.css
Four things the page needs and TemplateStyles cannot carry, all scoped to
rootpage-index, which is the class the translations carry too:mask-imageis not colour-typed, so avar()in one cannot be checked. Masks rather than images because an uploaded SVG is a fixed-colour picture that cannot follow the theme, and rather than a filter because a filter can only invert or rotate the colours a file already has.@keyframesis not a rule the sanitised stylesheet can rely on.MediaWiki:Mainpage-title, which this site cannot use: that message is read only for the pageTitle::isMainPage()is true of, and pointingMediaWiki:MainpageatSpecial:MyLanguage/indexto keep the logo following the reader's language is what stops it being that page. Clipped rather than removed, so the heading stays in the accessibility tree.The language bar moves to the foot as well —
<languages />renders where it is put, so that is a move and not a hiding.Spacing and shape
Both come from a reference page given during review. Its section unit is 4rem; bands here are 6rem apart, 7 around the diagram, cards 4rem apart with 2rem inside them, 7rem above the closing rule. Its feature cards are outlined boxes with a 1rem radius and no fill, which is what makes them read as roomy rather than as padded lozenges, so the cards and the diagram's panes are built that way. Type goes up with it: headings 2rem, card titles 1.375, bodies and the lede 1.125–1.25.
Not taken from it: the warm near-black palette, because this site has its own teal and has to serve the reader's own light or night theme; the weight-100 body text, because the face here is whatever the skin sets and a missing weight is synthesised badly or ignored; and the stacked gradients on its hero, which would fight the theme rather than follow it.
Layout
Every band is a
<div>outside the translate tags, so no layout markup reaches a translator — the same ruleTemplate:prevnext/docsets out.One measure for sentences, 36rem, and none for the objects: the diagram, the cards and the rules run the column. Prose inset while the objects reach the right edge is a measure; prose inset while nothing reaches it is what read as the page having slipped left.
The cards use a flex basis rather than a grid track, because a grid track minimum does not shrink: a 20rem floor is 320px, and a phone with about that much content box overflowed into a horizontal scroll on the page a phone is likeliest to land on.
Translation
Every unit on
indexchanged at some point in this branch, soindex/kois rewritten and restamped throughout, andLimitations/kois written from scratch. Verified withStalenessComputer::analyze()after each pass: no unit on either page is stale, untranslated, or orphaned.check-translationsagrees.Notes
previewat every pass, in Citizen light and dark, at desktop and at phone width. What the renders caught, in order: a fourth card orphaned onto its own row; the demo drawn in a frame inside a frame; the hero's rule stopping short of the column; a phrase broken across a line with a middot between it and its own tail; the logo appearing twice; the demo reading as two code blocks; the panes collapsing to hairlines once stacked; and a scrollbar under the diagram on a desktop. All fixed here.content: ""pseudo-element is not announced at all); that theecholine was 44 characters when it is 41; and that a container query was needed to know the column was narrow, when a narrow viewport implies it.MediaWiki:Common.css. They do not conflict — verified withgit merge-tree— so either can merge first.Deferred:
Template:prevnext/labelnow has two callers and is arguably no longer prevnext's. Renaming it toTemplate:labelis left for later.