diff --git a/docs/Limitations.wikitext b/docs/Limitations.wikitext new file mode 100644 index 000000000..b6bf2fdc6 --- /dev/null +++ b/docs/Limitations.wikitext @@ -0,0 +1,36 @@ +__TOC__ + + + + +A published {{SITENAME}} site is files: HTML, CSS, JavaScript and images, with nothing running +behind them. Anything MediaWiki does by answering a request when a reader asks for it is therefore +not part of the export. This page is the list, and what stands in for each where anything does. + + +== What a live wiki does and an export does not == + + +* All special pages, and the action API behind them +* All editors ([https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:WikiEditor WikiEditor], [https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:VisualEditor VisualEditor] and [https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:CodeEditor CodeEditor]); you edit the source files instead +* Accounts, and everything keyed to one: preferences, watchlists, notifications, user pages +* Page histories and diffs +* Discussion pages as a workflow, and recent-changes feeds + + +== What stands in for them == + + +; Editing and history +: Your repository. The "Edit", "View history" and "View source" links on each page lead to the page's source file there, wherever you host it; see [[Special:MyLanguage/Configuration#WikvenEditUrl|WikvenEditUrl]] and the two settings beside it. +; Reading preferences +: A [[Special:MyLanguage/Skins#Settings|Settings page]] the build writes, carrying the reader's colour theme and, where a site builds more than one skin, which skin to read it in. +; Search +: [[Special:MyLanguage/Searching|Done in the browser]]. The build writes a search index alongside the pages and the search box queries that. +; Special:Version +: The [[Special:MyLanguage/Configuration#WikvenAboutPage|About page]], where the build lists the software, extensions and skins the site was made with. + + +{{prevnext}} diff --git a/docs/Limitations/ko.wikitext b/docs/Limitations/ko.wikitext new file mode 100644 index 000000000..e2608bcd4 --- /dev/null +++ b/docs/Limitations/ko.wikitext @@ -0,0 +1,28 @@ + +제한 사항 + + +게시된 {{SITENAME}} 사이트는 파일입니다. HTML, CSS, JavaScript, 이미지가 있을 뿐 그 뒤에서 돌아가는 것은 없습니다. 그래서 MediaWiki가 독자의 요청을 그때그때 받아 처리하던 일은 내보내기에 포함되지 않습니다. 이 문서가 그 목록이며, 대신할 것이 있는 경우 무엇이 대신하는지도 함께 적었습니다. + + +== 구동 중인 위키는 하고 내보내기는 못하는 것 == + + +* 모든 특수 문서와 그 뒤의 action API +* 모든 편집기 ([$1 WikiEditor], [$2 시각편집기], [$3 CodeEditor]). 대신 소스 파일을 편집합니다 +* 계정, 그리고 계정에 딸린 모든 것: 환경 설정, 주시문서 목록, 알림, 사용자 문서 +* 문서 역사와 차이 +* 작업 흐름으로서의 토론 문서, 그리고 최근 바뀜 피드 + + +== 그 자리를 대신하는 것 == + + +; 편집과 역사 +: 리포지터리입니다. 각 문서의 "편집", "역사 보기", "원본 보기" 링크는 어디에 두었든 그곳의 소스 파일로 이어집니다. [[$1|WikvenEditUrl]]과 그 옆의 두 설정을 참고하세요. +; 표시 설정 +: 빌드가 쓰는 [[$2|설정 문서]]로, 독자의 색 테마와, 스킨을 여러 개 빌드한 사이트라면 어떤 스킨으로 읽을지를 담고 있습니다. +; 검색 +: [[$3|브라우저에서]] 이루어집니다. 빌드가 문서 옆에 검색 색인을 함께 쓰고, 검색창은 그 색인에 질의합니다. +; Special:Version +: [[$4|소개 문서]]입니다. 사이트를 만드는 데 쓰인 소프트웨어·확장 기능·스킨을 빌드가 여기에 나열합니다. diff --git a/docs/MediaWiki:Common.css b/docs/MediaWiki:Common.css index 4aab2d755..9fab1b8a6 100644 --- a/docs/MediaWiki:Common.css +++ b/docs/MediaWiki:Common.css @@ -175,3 +175,198 @@ body:not(.skin-citizen) .mw-parser-output a.external { #footer-places-desktop-toggle { display: none; } + +/* The landing page's filled button, defined here because TemplateStyles drops a custom-property + * declaration and so cannot make a token, only read one. It has to be a pair and it has to + * invert: night mode moves --color-progressive to a pale teal that white text sits on at + * 2.07:1, while the brand teal it replaces sits on the night ground at 3.2:1 -- so a button + * pinned to either one stops being the loudest thing on the page in half the sessions. Light + * teal with near-black text is 8.9:1 against both the text and the ground. + * + * Scoped to the landing page by its root-page class, which is the one the translations carry + * too: the body of index/ko is page-index_ko, and only rootpage-index catches both. The + * selectors are core's own darkmode-override() pair, the same as the tokens above. */ +.rootpage-index .mw-parser-output { + --wikven-cta-bg: #10707f; + --wikven-cta-bg--hover: #0d5c68; + --wikven-cta-fg: #fff; +} + +@media screen { + html.skin-theme-clientpref-night .rootpage-index .mw-parser-output { + --wikven-cta-bg: #4ec3da; + --wikven-cta-bg--hover: #79d0e0; + --wikven-cta-fg: #101418; + } +} + +@media screen and (prefers-color-scheme: dark) { + html.skin-theme-clientpref-os .rootpage-index .mw-parser-output { + --wikven-cta-bg: #4ec3da; + --wikven-cta-bg--hover: #79d0e0; + --wikven-cta-fg: #101418; + } +} + +/* The landing page sets its own tagline where a page title would go, so the title is taken out + * of the flow there and nowhere else. + * + * MediaWiki has a native way to do exactly this -- blanking MediaWiki:Mainpage-title and + * MediaWiki:Mainpage-title-loggedin -- and this site cannot use it. Those messages are only read + * 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; the cost of that, which Editing sidebar sets out, is that the wiki stops recognising + * the page as its main page. Keeping the logo is worth more than saving these seven lines. + * + * Clipped rather than display: none, so the heading stays in the accessibility tree: the page + * still has its h1 for a reader who is not looking at it, and only the sighted reader is spared + * the site name twice over. + * + * Here rather than in the page's own TemplateStyles because TemplateStyles prefixes every + * selector with .mw-parser-output and the heading is outside the parser output. rootpage- so + * that the translations (index/ko) are covered by the same rule as the source page; page- as + * well, so the source page is covered even where the root class is not written. */ +.page-index #firstHeading, +.rootpage-index #firstHeading { + position: absolute; + overflow: hidden; + clip-path: inset(50%); + inline-size: 1px; + block-size: 1px; + white-space: nowrap; +} + +/* The diagram's file-type marks, and the caret in the command beside them. + * + * Both are here rather than in the page's own TemplateStyles because that file can carry + * neither: a mask-image is not colour-typed, so a var() in one cannot be checked and the whole + * declaration is dropped, and @keyframes is not a rule it can rely on either. This file is not + * sanitised, and the external-link arrow above is already a data-URI SVG, so the mechanism is one + * the site has proven. + * + * Masks rather than images, and rather than a filter. An uploaded SVG placed with [[File:...]] is + * a fixed-colour picture that cannot follow the theme -- the problem the arrow above solves by + * carrying two copies of itself -- and a filter could only invert or rotate the colours the file + * already has, which a set of five does not survive. A mask throws the source's colours away and + * paints the shape in whatever colour the rule gives it, so two glyphs serve every type in both + * themes. + * + * Only the four named types are marked. Anything else keeps the space, so the names in a tree + * still start on the same edge, and nothing is drawn in it. */ +.rootpage-index .wikven-home-f::before { + content: ""; + display: inline-block; + inline-size: 1rem; + block-size: 1rem; + margin-inline-end: 0.45rem; + vertical-align: -0.18rem; +} + +.rootpage-index .wikven-home-f--wikitext::before, +.rootpage-index .wikven-home-f--html::before, +.rootpage-index .wikven-home-f--css::before, +.rootpage-index .wikven-home-f--dir::before { + -webkit-mask: + url("data:image/svg+xml,") + no-repeat center / contain; + mask: + url("data:image/svg+xml,") + no-repeat center / contain; +} + +.rootpage-index .wikven-home-f--dir::before { + -webkit-mask-image: url("data:image/svg+xml,"); + mask-image: url("data:image/svg+xml,"); +} + +/* .wikitext takes the brand teal, which makes the source pane one colour against a mixed output + * pane: one kind of thing goes in and several come out, said in colour rather than in a sentence. + * The other three are their own conventions, darkened for the light ground and lifted for the + * night one. These are graphics and want 3:1, which every pair here clears on both grounds. */ +.rootpage-index .wikven-home-f--wikitext::before { + background-color: #10707f; +} + +.rootpage-index .wikven-home-f--html::before { + background-color: #b3541e; +} + +.rootpage-index .wikven-home-f--css::before { + background-color: #2b6cb0; +} + +.rootpage-index .wikven-home-f--dir::before { + background-color: #54595d; +} + +@media screen { + html.skin-theme-clientpref-night + .rootpage-index + .wikven-home-f--wikitext::before { + background-color: #4ec3da; + } + + html.skin-theme-clientpref-night + .rootpage-index + .wikven-home-f--html::before { + background-color: #e8a06a; + } + + html.skin-theme-clientpref-night .rootpage-index .wikven-home-f--css::before { + background-color: #7fb3f0; + } + + html.skin-theme-clientpref-night .rootpage-index .wikven-home-f--dir::before { + background-color: #a2a9b1; + } +} + +@media screen and (prefers-color-scheme: dark) { + html.skin-theme-clientpref-os + .rootpage-index + .wikven-home-f--wikitext::before { + background-color: #4ec3da; + } + + html.skin-theme-clientpref-os .rootpage-index .wikven-home-f--html::before { + background-color: #e8a06a; + } + + html.skin-theme-clientpref-os .rootpage-index .wikven-home-f--css::before { + background-color: #7fb3f0; + } + + html.skin-theme-clientpref-os .rootpage-index .wikven-home-f--dir::before { + background-color: #a2a9b1; + } +} + +/* The caret is what makes the middle of the diagram read as a command rather than as a label with + * a dollar sign in front of it. A reader who has asked for less motion gets it still. */ +@keyframes wikven-caret { + 0%, + 100% { + opacity: 1; + } + + 50% { + opacity: 0; + } +} + +.rootpage-index .wikven-home-machine::after { + content: ""; + display: inline-block; + inline-size: 0.55em; + block-size: 1.05em; + margin-inline-start: 0.35em; + vertical-align: -0.2em; + background-color: currentcolor; + animation: wikven-caret 1.1s step-end infinite; +} + +@media (prefers-reduced-motion: reduce) { + .rootpage-index .wikven-home-machine::after { + animation: none; + } +} diff --git a/docs/MediaWiki:Sidebar-limitations.wikitext b/docs/MediaWiki:Sidebar-limitations.wikitext new file mode 100644 index 000000000..82e5dc554 --- /dev/null +++ b/docs/MediaWiki:Sidebar-limitations.wikitext @@ -0,0 +1 @@ +Limitations diff --git a/docs/MediaWiki:Sidebar-limitations/ko.wikitext b/docs/MediaWiki:Sidebar-limitations/ko.wikitext new file mode 100644 index 000000000..2a360c92f --- /dev/null +++ b/docs/MediaWiki:Sidebar-limitations/ko.wikitext @@ -0,0 +1 @@ +제한 사항 diff --git a/docs/MediaWiki:Sidebar.wikitext b/docs/MediaWiki:Sidebar.wikitext index 4b93171d8..bdf50888e 100644 --- a/docs/MediaWiki:Sidebar.wikitext +++ b/docs/MediaWiki:Sidebar.wikitext @@ -20,6 +20,7 @@ ** Special:MyLanguage/Deploying|sidebar-deploying ** Special:MyLanguage/Troubleshooting|sidebar-troubleshooting * sidebar-references +** Special:MyLanguage/Limitations|sidebar-limitations ** Special:MyLanguage/Configuration|sidebar-configuration ** Special:MyLanguage/Standalone binary|sidebar-standalone-binary ** Special:MyLanguage/Commands|sidebar-commands diff --git a/docs/Note icon.svg b/docs/Note icon.svg index 438a31958..67654ed32 100644 --- a/docs/Note icon.svg +++ b/docs/Note icon.svg @@ -1,6 +1,6 @@ Note - + diff --git a/docs/Template:home.wikitext b/docs/Template:home.wikitext new file mode 100644 index 000000000..404d4aa0b --- /dev/null +++ b/docs/Template:home.wikitext @@ -0,0 +1,3 @@ + +{{home/doc}} + diff --git a/docs/Template:home/doc.wikitext b/docs/Template:home/doc.wikitext new file mode 100644 index 000000000..e16773819 --- /dev/null +++ b/docs/Template:home/doc.wikitext @@ -0,0 +1,119 @@ +The landing page's layout: {{home}} loads the stylesheet, and +{{home/route|Installation}} is one of the buttons that start a reader off. + +== Why a template at all == + +{{home}} takes no arguments and renders nothing. It exists so the +stylesheet's name is written down once, in the same shape as +{{prevnext}}, rather than in a bare + on the page itself. + +{{home/route}} takes a page name, and a second argument of any value +makes that button the filled one. The label is the target's own translated title, read by +Template:prevnext/label — the same lookup, and for the same reason, that the +bottom-of-page navigation uses: a label written into the call would be a second copy of a title +that is already translated once, and one nothing checks. + +== Why the layout is not in the page == + +Every band of the page is a <div> outside the translate tags, so no layout +markup reaches a translator: a unit is a sentence, and moving a band or changing a card's border +is not a change to any sentence. That is the same rule Template:prevnext/doc sets out. + +== What the bands are for == + +The landing page carries what a reader who has just arrived needs, and sends the rest to the +documentation. In order: a tagline and two buttons; the rule the tool follows, then the diagram +that shows it; four things {{SITENAME}} can do at a line apiece; where it fits and what it is +instead of; one more button; the fine print. Everything else was moved or cut — the list of what a +static export cannot do is an appendix now, on +[[Special:MyLanguage/Limitations|Limitations]], because a landing page that answers "should I use +this" with a list of what is missing has answered the wrong question first. + +The bands are short on purpose and the page is long on purpose: a reader scrolls, and would rather +scroll past four lines than read four paragraphs. + +== The diagram == + +Source in, one command, site out. 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-highlight box with no tokens in it, so no +styling of the wrapper could have said anything else. Both trees are ordinary markup now, and the +command between them is the only filled object on the page besides the button, because it is the +only thing on the page that does something. + +On a narrow screen it stacks, and the arrows turn to match. A viewport query is the wrong +instrument for most of this stylesheet, because the content column is a different width in each +skin and the viewport does not say which; it is the right one here, because a wide column cannot +happen inside a narrow viewport. "The viewport is small" does imply "the column is small", even +though the reverse does not hold, and below that width the row could not fit anyway. + +The arrows 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 — a transform would be a +second way of saying the same thing and one more property to be dropped. + +The arrows are drawn from logical borders, so they turn themselves around for a right-to-left +reader, and they are empty elements rather than text, so they are never announced — the two pane +labels carry the direction for a reader who is not looking. + +== What is in MediaWiki:Common.css instead == + +Three things the page needs and TemplateStyles cannot carry, all of them scoped to +rootpage-index, which is the class the translations carry too: + +; the filled button's two colours +: TemplateStyles drops a custom-property declaration, so a token can be read here but not made. +; the file-type marks +: A mask-image is not colour-typed, so a var() in one cannot be checked +and the declaration would be dropped. They are 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 the file already has. +; the caret in the command +: @keyframes is not a rule this stylesheet can rely on. It stops under +prefers-reduced-motion. + +The page title is taken out of the flow there too. MediaWiki's own way to do that is to blank +MediaWiki:Mainpage-title, which this site cannot use — that message is read only for +the page Title::isMainPage() is true of, and pointing MediaWiki:Mainpage +at Special:MyLanguage/index to keep the logo following the reader's language is what +stops it being that page. The heading is clipped rather than removed, so it is still there for a +reader who is not looking. + +== The language bar == + + is at the foot of the page rather than the head. It +renders where it is put, so this is a move and not a hiding: a reader arriving at a landing page is +deciding whether to read at all, not which language to read in, and each skin carries a language +control of its own for the reader who wants one sooner. + +Translate's "this page is a translated version" notice is still at the head and is not touched, +because the stylesheet cannot reach it either: TemplateStyles prefixes every selector with +.mw-parser-output, and that notice is written before the parser output. + +== Colours == + +The stylesheet reads the skin's Codex custom properties and defines none. All three skins redefine +the Codex set for night mode, so reading the tokens is what makes the page follow the reader's +theme without knowing which one it is. + +Every shape the page draws — the arrows, the tree's trunk and its ticks — comes out of +border-*-color or background-color, both of which are colour-typed and so +may read a token. A var() inside linear-gradient() cannot be +type-checked, so the whole declaration is dropped, silently. That is the trap here. + +== Measures and lengths == + +One measure for sentences, 36rem, and none at all 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 to the left. The tagline's cap is +the exception, and it exists to control where the line breaks in any language rather than to set a +reading width. + +Lengths come from 0.5 / 0.75 / 1 / 1.5 / 2 / 2.5 / 4 / 6 / 7 rem and nowhere else. A length cannot +be tokenised here — TemplateStyles drops the declaration — so the scale is kept by hand, and the +next editor inherits the rule from the stylesheet's own header rather than inheriting the values. +Bands are 6rem apart, 7 around the diagram, which is the band worth looking at. + +The cards are laid out with 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. A basis collapses instead. diff --git a/docs/Template:home/route.wikitext b/docs/Template:home/route.wikitext new file mode 100644 index 000000000..86e52720e --- /dev/null +++ b/docs/Template:home/route.wikitext @@ -0,0 +1,3 @@ +
[[Special:MyLanguage/{{{1}}}|{{prevnext/label|{{{1}}}}}]]
+{{home/doc}} + diff --git a/docs/Template:home/styles.css b/docs/Template:home/styles.css new file mode 100644 index 000000000..744e93696 --- /dev/null +++ b/docs/Template:home/styles.css @@ -0,0 +1,461 @@ +/* The landing page. + * + * Colours are read from the skin's Codex custom properties and never written here: all three + * skins redefine that set for night mode, so the page follows the reader's theme without + * knowing anything about it. The literal in each var() is the light value, a fallback for a + * skin that defines none. Defining one is not an option -- TemplateStyles drops a + * custom-property declaration, and drops it silently. + * + * Two things this file deliberately does not do, both of them in MediaWiki:Common.css instead, + * scoped to this page: the file-type marks in the diagram, which are SVG masks, and the caret + * that blinks in the command. A mask-image is not colour-typed, so a var() in one cannot be + * checked and the declaration would go; @keyframes is not a rule this file can rely on either. + * Common.css is not sanitised and already carries a data-URI SVG for the external-link arrow. + * + * Every shape drawn here comes out of border-*-color or background-color, both colour-typed and + * so able to read a token. A var() inside linear-gradient() cannot be type-checked and the whole + * declaration is dropped, silently; that is the trap to know about. + * + * Widths come from the container, not from media queries. The content column is a different + * width in each of the three skins, and in Vector it is a reader preference besides, so the + * viewport says nothing useful about the space a band actually has. + * + * One measure for sentences, 36rem, and none at all for the objects: the diagram, the cards and + * the rules run the column. Prose inset while the objects reach the edge is a measure; prose + * inset while nothing reaches it is what read as the page having slipped to the left. + * + * Lengths come from 0.5 / 0.75 / 1 / 1.5 / 2 / 2.5 / 4 / 6 / 7 rem and nowhere else, and the + * interval between bands is 6rem, 7 around the diagram, which is the band worth looking at. + * There is no way to tokenise a length here, so the scale is kept by hand. + */ + +/* No rule under the hero. The skin draws one under the title and another under the tab row, so a + * third within a couple of hundred pixels made the page's own rule indistinguishable from the + * furniture above it. The closing band keeps its rule and is the only one the page draws. */ +.wikven-home-hero { + margin-block: 4rem 6rem; +} + +/* The cap is stated so the line breaks into two or three whatever language it is in. It is not + * tuned to the English string, which is what a cap in ch would have been -- Hangul is about two + * ch wide, so a cap set for English would fold the Korean tagline into a column. */ +.wikven-home-tagline { + margin-block: 0 1.5rem; + max-inline-size: 34rem; + font-size: 3.25rem; + font-weight: bold; + letter-spacing: -0.02em; + line-height: 1.05; + color: var(--color-emphasized, #101418); +} + +.wikven-home-sub { + margin-block: 0 2.5rem; + max-inline-size: 36rem; + font-size: 1.375rem; + line-height: 1.55; + color: var(--color-base, #202122); +} + +.wikven-home-cta { + display: flex; + flex-wrap: wrap; + gap: 1rem; +} + +/* A floor rather than a width: "설치" is two characters and would otherwise ship as a stub beside + * a button three times its size, while a longer language still grows to fit. */ +.wikven-home-route a { + display: block; + padding: 0.625rem 1.75rem; + min-inline-size: 9rem; + border-radius: 0.5rem; + font-size: 1.125rem; + font-weight: bold; + line-height: 2; + text-align: center; +} + +/* The two colours come from MediaWiki:Common.css, which can declare a custom property where this + * file cannot. They have to be a pair and they have to invert: night mode moves the accent to a + * pale teal, which white text sits on at 2.07:1, and the brand teal it replaces sits on the night + * ground at 3.2:1 -- a button that stops being the loudest thing on the page in half the + * sessions. Pale teal with near-black text is 8.9:1 both ways. */ +.wikven-home-route-primary a { + border: 1px solid var(--wikven-cta-bg, #10707f); + background-color: var(--wikven-cta-bg, #10707f); + color: var(--wikven-cta-fg, #fff); +} + +.wikven-home-route-primary a:hover { + border-color: var(--wikven-cta-bg--hover, #0d5c68); + background-color: var(--wikven-cta-bg--hover, #0d5c68); +} + +/* The secondary button has no background of its own, so it can read the accent token and be + * whichever teal the theme is using. */ +.wikven-home-route-secondary a { + border: 1px solid var(--border-color-base, #a2a9b1); + background-color: transparent; + color: var(--color-progressive, #10707f); +} + +.wikven-home-route-secondary a:hover { + border-color: var(--color-progressive, #10707f); + background-color: var(--background-color-interactive-subtle, #f8f9fa); +} + +/* Its own rule, so that a pseudo-class the sanitiser does not know cannot take the hover rules + * down with it -- one bad selector drops the whole list. The ring is stated rather than left to + * the browser, which would draw a dark one on the pale teal button in night mode. */ +.wikven-home-route a:focus-visible { + outline: 2px solid var(--color-emphasized, #101418); + outline-offset: 2px; +} + +.wikven-home-section { + margin-block: 0 6rem; +} + +/* The page's proof gets more room than the list of features after it. */ +.wikven-home-section-demo { + margin-block: 0 7rem; +} + +/* Sentence case, at a size that can carry the page's structure. It was a tracked-out caps label, + * which is a device for an eyebrow above a headline and was here doing the heading's whole job in + * the page's quietest type -- and it only ever worked in Latin script: text-transform does + * nothing to Hangul while the letter-spacing still loosens it. + * + * MediaWiki 1.43+ wraps a heading in
, and the skins hang the rule under + * a section heading off one or the other, so both are cleared. */ +.wikven-home-section .mw-heading, +.wikven-home-section h2 { + margin-block: 0 1.5rem; + padding-block: 0; + border: 0; + font-family: inherit; + font-size: 2rem; + font-weight: bold; + letter-spacing: normal; + line-height: 1.25; + text-transform: none; + color: var(--color-emphasized, #101418); +} + +/* The rule stated before it is shown, at reading size. It was underneath the demonstration in the + * page's quietest type, which is a footnote to a thing the reader has already worked out. */ +.wikven-home-lede { + margin-block: 0 2rem; + max-inline-size: 36rem; + font-size: 1.25rem; + line-height: 1.6; + color: var(--color-base, #202122); +} + +/* The diagram: source in, one command, site out. + * + * The row stacks below 46em and the arrows turn with it; see the media query further down. This + * overflow is the backstop under that -- a column too narrow even for the panes' own floors + * scrolls the diagram rather than pushing the page sideways. */ +.wikven-home-flow-scroll { + overflow-x: auto; +} + +/* No min-content floor on the row. With it, the row refused to be narrower than the longest + * file name in either tree -- the trees are nowrap, so their min-content is that name -- and + * the gloss on the search index pushed the total past the column, which is what put a scrollbar + * under the diagram on a desktop. The panes have a floor of their own and each tree scrolls + * inside its own pane, so a long name moves the name rather than the diagram. */ +.wikven-home-flow { + display: flex; + align-items: center; + gap: 1.5rem; +} + +/* Outlined and rounded, with room in it, and no fill: a box that is mostly padding reads as + * padding, and a filled one would not survive night mode anyway -- the subtle background token + * against the page ground is about 1.1:1 there. The label strip is clipped to the radius. */ +.wikven-home-pane { + overflow: hidden; + flex: 1 1 0; + min-inline-size: 15rem; + border: 1px solid var(--border-color-muted, #dadde3); + border-radius: 1rem; +} + +.wikven-home-pane-label { + padding: 0.75rem 1.5rem; + border-block-end: 1px solid var(--border-color-muted, #dadde3); + background-color: var(--background-color-neutral-subtle, #f8f9fa); + font-size: 0.875rem; + font-weight: bold; + color: var(--color-base, #202122); +} + +/* A directory, not code. Writing the output as a second made the band read as + * two code blocks that happened to be adjacent, which is what it was: lang="text" produces a + * .mw-highlight box with no tokens in it. */ +.wikven-home-tree { + padding: 1.5rem; + font-family: monospace; + font-size: 1rem; + overflow-x: auto; + line-height: 1.9; + white-space: nowrap; + color: var(--color-base, #202122); +} + +/* One line in the output tree is a product name rather than a file type, so it says what it is. + * The other three are read off their extensions and need nothing. */ +.wikven-home-gloss { + margin-inline-start: 0.75rem; + color: var(--color-subtle, #54595d); +} + +.wikven-home-gloss p { + display: inline; + margin: 0; +} + +.wikven-home-tree-root { + font-weight: bold; + color: var(--color-emphasized, #101418); +} + +.wikven-home-tree-branch { + margin-inline-start: 0.5rem; +} + +/* The trunk. */ +.wikven-home-tree-item { + border-inline-start-width: 1px; + border-inline-start-style: solid; + border-inline-start-color: var(--border-color-base, #a2a9b1); +} + +/* The tick off it: an inline box that is nothing but a bottom border. */ +.wikven-home-tree-item::before { + content: ""; + display: inline-block; + inline-size: 0.75rem; + block-size: 0; + margin-inline-end: 0.5rem; + vertical-align: middle; + border-block-end-width: 1px; + border-block-end-style: solid; + border-block-end-color: var(--border-color-base, #a2a9b1); +} + +/* The last item's trunk would otherwise run half a line past its own tick, so the stem moves into + * the pseudo-element and stops there. If :last-child is dropped, what is left is one hairline + * overhanging in a muted colour. */ +.wikven-home-tree-item:last-child { + border-inline-start-color: transparent; +} + +.wikven-home-tree-item:last-child::before { + block-size: 0.95rem; + vertical-align: top; + border-inline-start-width: 1px; + border-inline-start-style: solid; + border-inline-start-color: var(--border-color-base, #a2a9b1); +} + +/* The arrows. Only borders and only logical sides, so they turn themselves around for a + * right-to-left reader, and they are pseudo-free empty elements rather than text, so they are + * never announced -- the pane labels carry the direction for a reader who is not looking. */ +.wikven-home-arrow { + display: flex; + flex-direction: column; + flex: 0 0 auto; + align-self: center; +} + +.wikven-home-arrow-line { + block-size: 0; + inline-size: 1.75rem; + border-block-start-width: 2px; + border-block-start-style: solid; + border-block-start-color: var(--border-color-base, #a2a9b1); +} + +.wikven-home-arrow-head { + align-self: flex-end; + inline-size: 0; + block-size: 0; + margin-block-start: -0.45rem; + border-block: 0.45rem solid transparent; + border-inline-start-width: 0.5rem; + border-inline-start-style: solid; + border-inline-start-color: var(--border-color-base, #a2a9b1); +} + +/* Stacked on a narrow screen, and the arrows turn to match. + * + * A viewport query is the wrong instrument for most of this stylesheet, because the content + * column is a different width in each skin and the viewport does not say which. It is the right + * one here: a wide column cannot happen inside a narrow viewport, so "the viewport is small" + * does imply "the column is small", even though the reverse does not hold. Below this width the + * row cannot fit anyway -- two 15rem panes, two arrows and four gaps come to about 39rem. + * + * The arrows 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; a transform would + * be a second way of saying the same thing and one more property to be dropped. */ +@media screen and (max-width: 46em) { + .wikven-home-flow { + flex-direction: column; + align-items: stretch; + min-inline-size: 0; + } + + /* flex-basis is measured along the main axis, and the main axis is now the block one, so the + * 1 1 0 that makes the panes share the row would here make them nought pixels tall -- and + * the container's height comes from its content, so there is no free space for the grow to + * hand back. They collapsed to their own borders. Stacked, a pane is as tall as it is. */ + .wikven-home-pane { + flex: 0 0 auto; + min-inline-size: 0; + } + + .wikven-home-arrow { + align-items: center; + align-self: center; + } + + .wikven-home-arrow-line { + inline-size: 0; + block-size: 1.75rem; + border-block-start-width: 0; + border-inline-start-width: 2px; + border-inline-start-style: solid; + border-inline-start-color: var(--border-color-base, #a2a9b1); + } + + .wikven-home-arrow-head { + align-self: center; + margin-block-start: 0; + border-inline: 0.45rem solid transparent; + border-block-start-width: 0.5rem; + border-block-start-style: solid; + border-block-start-color: var(--border-color-base, #a2a9b1); + border-block-end-width: 0; + } + + .wikven-home-machine { + align-self: center; + } +} + +/* The command in the middle is the only filled object on the page besides the button, because it + * is the only thing on the page that does something. Its caret blinks; that is in Common.css. */ +.wikven-home-machine { + flex: 0 0 auto; + padding: 1.25rem 1.75rem; + border: 1px solid var(--wikven-cta-bg, #10707f); + border-radius: 1rem; + background-color: var(--wikven-cta-bg, #10707f); + font-family: monospace; + font-size: 1rem; + white-space: nowrap; + color: var(--wikven-cta-fg, #fff); +} + +.wikven-home-prompt { + opacity: 0.65; +} + +.wikven-home-cards { + display: flex; + flex-wrap: wrap; + gap: 4rem; +} + +/* A flex basis rather than a grid track, because a grid track minimum does not shrink: an 18rem + * floor is 288px and a 320px phone has about that much content box, so the grid overflowed on the + * page a phone is likeliest to land on. A basis collapses instead. */ +.wikven-home-card { + flex: 1 1 20rem; + padding: 2rem; + border: 1px solid var(--border-color-muted, #dadde3); + border-radius: 1rem; +} + +/* No hover on the card: the title is a link and the card is not, and there is no JavaScript here + * to make one. A card-wide hover state would be a lie about what is clickable. */ +.wikven-home-card-title { + margin-block-end: 0.75rem; + font-size: 1.375rem; + font-weight: bold; + line-height: 1.3; +} + +.wikven-home-card-body { + font-size: 1.125rem; + line-height: 1.6; + color: var(--color-base, #202122); +} + +/* A heading and one paragraph. It was three phrases on one line under a 2rem heading, which is + * eleven words wearing a whole section's worth of structure: not a sentence and not a list, so it + * read as a caption that had lost its bullets. 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. */ +.wikven-home-fits { + max-inline-size: 36rem; + font-size: 1.125rem; + line-height: 1.6; + color: var(--color-base, #202122); +} + +/* A rule and a size, not a box. The button goes to the far edge so both ends of the rule are + * anchored rather than leaving half the column empty beside it. */ +.wikven-home-closing { + display: flex; + flex-wrap: wrap; + gap: 1rem 2rem; + align-items: center; + justify-content: space-between; + margin-block: 7rem 3rem; + padding-block-start: 4rem; + border-block-start: 1px solid var(--border-color-subtle, #c8ccd1); +} + +.wikven-home-closing-line { + max-inline-size: 34rem; + font-size: 1.75rem; + font-weight: bold; + line-height: 1.25; + color: var(--color-emphasized, #101418); +} + +.wikven-home-fineprint { + margin-block-start: 3rem; + max-inline-size: 36rem; + font-size: 0.875rem; + line-height: 1.6; + color: var(--color-subtle, #54595d); +} + +/* Translate's language bar. It renders wherever is put, and on this page that is + * the foot: a reader arriving at a landing page is choosing whether to read at all, not which + * language to read in, and every skin here carries a language control of its own for the reader + * who wants one sooner. Nothing is hidden, so it stays one tab stop from the end of the page + * rather than one from the start. */ +.wikven-home-languages { + margin-block-start: 4rem; + font-size: 0.875rem; +} + +/* Load-bearing and it does not look it: every band that holds a translate block needs its + * paragraph margin cleared, so a new band has to be added here in the same edit. There is no + * :is() or :where() to shorten this with -- the sanitiser drops any rule that uses one. */ +.wikven-home-sub p, +.wikven-home-lede p, +.wikven-home-pane-label p, +.wikven-home-card-title p, +.wikven-home-card-body p, +.wikven-home-fits p, +.wikven-home-closing-line p, +.wikven-home-fineprint p { + margin: 0; +} diff --git a/docs/index.wikitext b/docs/index.wikitext index eb1651038..437fb3e9b 100644 --- a/docs/index.wikitext +++ b/docs/index.wikitext @@ -1,57 +1,184 @@ - +__NOTOC__ +{{home}} + +
+
-{{SITENAME}} is a static site generator built on [https://www.mediawiki.org/ MediaWiki], the software -behind [https://www.wikipedia.org/ Wikipedia]. It turns a directory of wikitext -into a plain HTML site you can host anywhere, with no server or database to run. -This documentation site is itself built with {{SITENAME}}. - +Bake wikitext into a website. + +
+
+ -Reach for {{SITENAME}} when your content is already MediaWiki wikitext, or when you -want MediaWiki's templates, parser functions, gadgets and extensions but a static -result with nothing to run: a project's documentation site, an archived wiki -you can browse as plain HTML, or a personal wiki. Unlike a general static-site generator -such as [https://gohugo.io/ Hugo] or [https://www.mkdocs.org/ MkDocs], it renders real wikitext through MediaWiki itself, so it -assumes you are comfortable with wikitext (see [[Special:MyLanguage/Why wikitext|Why wikitext]] for the trade-offs). +{{SITENAME}} renders your wikitext through [https://www.mediawiki.org/ MediaWiki] at build time and writes out +plain HTML. Nothing runs behind the published site. + +
+
{{home/route|Getting Started|primary}}{{home/route|Installation}}
+
+
+ -See [[Special:MyLanguage/Installation|Installation]] for the three ways to install {{SITENAME}}, the standalone -[[Special:MyLanguage/Installation#Binary|binary]], the [[Special:MyLanguage/Installation#Docker|Docker image]], or -[[Special:MyLanguage/Installation#Build from source|from source]], then [[Special:MyLanguage/Getting Started|Getting Started]] to build -your first site. - +== How it works == + +
+ -== Supported features == +Every .wikitext file becomes a page. + +
+
+
+
+ + +Your source + +
+
+
src/
+
index.wikitext
Getting Started.wikitext
Template:note.wikitext
+
+
$ wikven build
+
+ + +Your site + +
+
+
dist/
+
index.html
Getting_Started.html
site.styles.css
pagefind/ + + +the search index + +
+
+
+
+
+
+ -With {{SITENAME}}, you can use the following features of MediaWiki. - +== What you get == + +
+
+ -* [https://www.mediawiki.org/wiki/Special:MyLanguage/Wikitext Wikitext] pages (see [[Special:MyLanguage/Pages|Pages]]) -* [[Special:MyLanguage/Pages#Templates|Templates]] -* [[Special:MyLanguage/Images|Images]] from Wikimedia Commons or local files -* [[Special:MyLanguage/JavaScript|JavaScript]] (MediaWiki:Common.js and gadgets) -* [[Special:MyLanguage/Extensions|Extensions]], bundled or fetched at build time, and [[Special:MyLanguage/Skins|skins]] — several at once, with a switcher for the reader -* [[Special:MyLanguage/Searching|Search]] (client-side, built in via SifterSearch) -* [[Special:MyLanguage/Translating|Translation]] into multiple languages (via the Translate extension) - +[[Special:MyLanguage/Pages#Templates|Templates, not copy-paste]] + +
+
+ -== Unsupported features == - +Templates, parser functions and Lua modules, all resolved at build time. + +
+
+
+ -These need a live wiki, so they are not part of the static export: - +[[Special:MyLanguage/Extensions|Extensions and skins]] + +
+
+ -* All special pages, and the action API behind them -* All editors ([https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:WikiEditor WikiEditor], [https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:VisualEditor VisualEditor] and [https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:CodeEditor CodeEditor]); you edit the source files instead -* Accounts, and everything keyed to one: preferences, watchlists, notifications, user pages -* Page histories and diffs, which live in your repository instead — the "View history" link leads there -* Discussion pages as a workflow, and recent-changes feeds - +Bundled or fetched from Git, with several skins for the reader to choose between. + +
+
+
+ -What replaces some of them is written down: the reader's own display choices are on a [[Special:MyLanguage/Skins#Settings|Settings page]] the build writes, and searching is [[Special:MyLanguage/Searching|done in the browser]]. +[[Special:MyLanguage/Searching|Search with nothing to query]] + +
+
+ + +The index is built with the site and runs in the reader's browser. + +
+
+
+ + +[[Special:MyLanguage/Translating|Every language you write in]] + +
+
+ + +Every language you write in comes out as its own set of pages. +
+
+
+ +
+ + +== Where it fits == + +
+ + +A project's documentation, an archived wiki, a personal wiki. Unlike a general static-site generator such as +[https://gohugo.io/ Hugo] or [https://www.mkdocs.org/ MkDocs], {{SITENAME}} renders real wikitext, so it suits content +that is already a wiki. See [[Special:MyLanguage/Why wikitext|Why wikitext]] for how the markup compares with +Markdown, and [[Special:MyLanguage/Limitations|Limitations]] for what a live wiki does that a published site cannot. + +
+
+ +
+
+ + +Your first site is one command away. + +
{{home/route|Getting Started|primary}}
+ +
+ + +This site is a {{SITENAME}} build. + +
+ +
+ +
{{DISPLAYTITLE:Wikven}} diff --git a/docs/index/ko.wikitext b/docs/index/ko.wikitext index 91609d396..ad721d95f 100644 --- a/docs/index/ko.wikitext +++ b/docs/index/ko.wikitext @@ -1,40 +1,59 @@ - -{{SITENAME}}은 [$2 Wikipedia]를 구동하는 소프트웨어인 [$1 MediaWiki]를 기반으로 한 정적 사이트 생성기입니다. 위키텍스트 디렉터리를 평범한 HTML 사이트로 바꿔 주는데, 어디서나 호스팅할 수 있고 구동할 서버나 데이터베이스가 필요 없습니다. 이 문서 사이트 또한 {{SITENAME}}으로 만들었습니다. - - -콘텐츠가 이미 MediaWiki 위키텍스트이거나, MediaWiki의 틀·파서 함수·소도구·확장 기능은 그대로 쓰면서 실행할 것이 없는 정적 결과물을 원할 때 {{SITENAME}}이 제격입니다. 프로젝트 문서 사이트, 평범한 HTML로 열람하는 보관용 위키, 개인 위키 같은 용도죠. [$2 Hugo]나 [$3 MkDocs] 같은 범용 정적 사이트 생성기와 달리 {{SITENAME}}은 MediaWiki로 진짜 위키텍스트를 렌더링하므로, 위키텍스트에 익숙하다는 것을 전제합니다 (장단점은 [[$1|위키텍스트를 쓰는 이유]] 참고). - - -{{SITENAME}}을 설치하는 세 가지 방법(단독 실행 [[$2|바이너리]], [[$3|Docker 이미지]], [[$4|소스에서 빌드]])은 [[$1|설치]] 문서에서 다루며, 첫 사이트를 만들려면 [[$5|시작하기]]로 이어집니다. - - -== 지원하는 기능 == - - -{{SITENAME}}에서는 MediaWiki의 다음 기능을 쓸 수 있습니다. - - -* [$8 Wikitext] 문서 ([[$1|문서]] 참고) -* [[$2|틀]] -* 위키미디어 공용이나 로컬 파일에서 가져온 [[$3|이미지]] -* [[$4|자바스크립트]] (MediaWiki:Common.js와 소도구) -* 번들되어 있거나 빌드 시 가져오는 [[$5|확장 기능]], 그리고 [[$9|스킨]] — 여러 개를 한꺼번에, 독자가 고를 수 있는 전환기와 함께 -* [[$6|검색]] (클라이언트 사이드, SifterSearch가 제공) -* 여러 언어로의 [[$7|번역]] (Translate 확장 기능을 통해) - - -== 지원하지 않는 기능 == - - -다음 기능은 실제로 구동 중인 위키가 있어야 하므로 정적 내보내기에는 포함되지 않습니다: - - -* 모든 특수 문서와 그 뒤의 action API -* 모든 편집기 ([$1 WikiEditor], [$2 시각편집기], [$3 CodeEditor]). 대신 소스 파일을 편집합니다 -* 계정, 그리고 계정에 딸린 모든 것: 환경 설정, 주시문서 목록, 알림, 사용자 문서 -* 문서 역사와 차이. 대신 저장소에 있으며, "역사 보기" 링크가 그곳으로 이어집니다 -* 작업 흐름으로서의 토론 문서, 그리고 최근 바뀜 피드 - - -그중 일부를 대신하는 것은 문서로 남겨 두었습니다. 독자 자신의 표시 선택은 빌드가 쓰는 [[$1|설정 문서]]에 있고, 검색은 [[$2|브라우저에서]] 이루어집니다. + +위키텍스트를 웹사이트로 구워 냅니다. + + +{{SITENAME}}은 빌드할 때 [$1 MediaWiki]로 위키텍스트를 렌더링해 평범한 HTML로 내보냅니다. 게시된 사이트 뒤에서는 아무것도 돌아가지 않습니다. + + +== 어떻게 만들어지나 == + + +.wikitext 파일은 하나하나가 문서가 됩니다. + + +소스 + + +사이트 + + +== 무엇을 쓸 수 있나 == + + +[[$1|복사·붙여넣기 대신 틀]] + + +틀과 파서 함수, Lua 모듈까지 전부 빌드할 때 처리됩니다. + + +[[$1|확장 기능과 스킨]] + + +번들되어 있거나 빌드할 때 Git에서 가져오며, 스킨은 여러 개를 실어 독자가 고르게 합니다. + + +[[$1|질의할 곳 없는 검색]] + + +색인이 사이트와 함께 만들어지고, 검색은 독자의 브라우저에서 이루어집니다. + + +[[$1|쓰는 모든 언어로]] + + +쓰는 언어마다 자기 문서 묶음으로 나옵니다. + + +== 어디에 어울리나 == + + +첫 사이트까지 명령 한 줄. + + +이 사이트도 {{SITENAME}} 빌드입니다. + + +프로젝트 문서 사이트, 보관용 위키, 개인 위키. [$1 Hugo]나 [$2 MkDocs] 같은 범용 정적 사이트 생성기와 달리 {{SITENAME}}은 진짜 위키텍스트를 렌더링하므로, 이미 위키인 콘텐츠에 잘 맞습니다. 마크업이 Markdown과 어떻게 다른지는 [[$3|위키텍스트를 쓰는 이유]]에, 구동 중인 위키가 하는 일 가운데 게시된 사이트가 할 수 없는 것은 [[$4|제한 사항]]에 적어 두었습니다. + + +검색 색인 diff --git a/docs/logo.png b/docs/logo.png index e30641b2d..0142141ca 100644 Binary files a/docs/logo.png and b/docs/logo.png differ diff --git a/docs/logo.svg b/docs/logo.svg index c016b7c50..2d1f34830 100644 --- a/docs/logo.svg +++ b/docs/logo.svg @@ -1,8 +1,8 @@ Wikven - - - + + +