CSS WG wiki hosting

[sideshowbarker]

Requirements that follow from discussion in #12743 that by month’s end, https://wiki.csswg.org content must move to other hosting.

1. Don’t break any existing https://wiki.csswg.org URLs. ✳️
2. The source for the content must continue to be “web editable” in some way similar to how it’s currently “web editable”.
3. The source for the content must be some flavor of Markdown. Users must not have to directly edit the content as HTML.
4. There must therefore be some means which displays/renders/generates/publishes HTML from the Markdown sources.
5. There must be an authentication/registration means to control who can make changes, and log who made which ones.

✳️ Requirement #1 above means we must keep the https://wiki.csswg.org domain/site — even if only for redirecting — and then either:

  A. The existing content needs to continue to be served from the same https://wiki.csswg.org URLs; or
  B. The https://wiki.csswg.org URLs need to redirect to URLs at some other domain.

[sideshowbarker]

Concrete proposal for a replacement

https://w3c.github.io/csswg-wiki/

How this proposal addresses the requirements

1. Don’t break any existing wiki.csswg.org URLs.

   Add to the csswg.org DNS these records:

    _github-pages-challenge-w3c.wiki.csswg.org.  TXT    "ca0fc182a3415a7e96abb943bcc587"
    wiki.csswg.org.                              CNAME  w3c.github.io.
   

   https://github.com/w3c/csswg-wiki already has wiki.csswg.org configured as a GitHub “Custom domain”; so, once the DNS for wiki.csswg.org has those records, wiki.csswg.org will serve its content from w3c.github.io/csswg-wiki.

2. The source for the content must continue to be “web editable” in some way similar to how it’s currently “web editable”.

   Every page served from https://w3c.github.io/csswg-wiki has en Edit button. Pressing that button opens up the GitHub web UI for editing the source of the page directly over the web, within a browser. That mechanism is functionally identical to the mechanism currently used by https://wiki.csswg.org/.

3. The source for the content must be some flavor of Markdown. Users must not have to directly edit the content as HTML.

   All https://w3c.github.io/csswg-wiki sources are Markdown files in version control in https://github.com/w3c/csswg-wiki.

4. There must therefore be some mechanism which generates/publishes HTML output from the Markdown sources.

   The published https://w3c.github.io/csswg-wiki HTML content is generated using Jekyll through GitHub Pages.

5. There must be an authentication/registration means to control who can make changes, and log who made which ones.

   • Users must be logged into GitHub to edit the https://w3c.github.io/csswg-wiki content.
   • The repo maintainers (e.g., CSS WG chairs, team contacts, other trusted WG members) have full, granular control of:
     • who can make edits at all
     • whether users can commit edits directly to the repo’s main branch, or some/all edits require creation of a PR
     • exactly which users are allowed (if anybody) to commit edits directly to the main branch without a PR, and which users must instead submit their edits as PRs (for review)

Notable aspects of the implementation of this proposal

 
Here are few things worth noting about the implementation of https://w3c.github.io/csswg-wiki:

Site design

As noted in https://github.com/w3c/csswg-wiki#frontend-design, the https://github.com/w3c/csswg-wiki site is:

• implemented with a modern, accessible, responsive frontend built with vanilla HTML, CSS, and JavaScript
• follows WCAG 2.1 AA guidelines
• looks great on mobile-phone/small-device screens, and has great UX even on such smaller screens
• works well cross-browser

Search feature

As noted in https://github.com/w3c/csswg-wiki#search, the site provides a (Lunr.js-based client-side) full-text search feature.

Markdown enhancements

As noted in https://github.com/w3c/csswg-wiki#conversion-process, the Markdown-to-HTML converter supports the following:

Definition-list conversion to HTML dl/dt/dd

To produce dl/dt/dd output in HTML, the following markdown can be used in the source:

Term
: Definition

Existing wiki.csswg.org content uses definition lists extensively — so it’s important that the replacement also support them.

GFM-style “alerts” (admonitions)

Admonitions can be represented in Markdown source using the same syntax supported in other GitHub content:

> [!IMPORTANT]
> Admonition content here

[plinss]

What an interesting concept, if only there was a term for something like that. (Checks notes) Oh yeah, the term is “Wiki”, you’ve invented a wiki. But a worse version of one.

Just going to leave this here for no apparent reason: https://en.wikipedia.org/wiki/Not_invented_here

[keithamus]

FWIW you can use the gollum event in GitHub actions to trigger some kind of build whenever the (GitHub) Wiki is edited. So this means we could retain the GitHub's Wiki, ensure that only collaborators can edit it, and whenever someone does edit it, it can run a GitHub action to generate a static site and publish it to for e.g. w3c.github.io/csswg-wiki. In other words the website would be a read-only copy of the GitHub backed wiki.

[fantasai]

The editing flow might not be quite as nice as a real wiki, but using GH-flavored markdown seems like an improvement, since everyone involved is familiar with it. I also appreciate that we're maintaining the URL hierarchy. So altogether this seems like a reasonable stop-gap replacement.

[fantasai]

@sideshowbarker Is there some kind of 301/302 redirect map in Jekyll? I know we'd set up redirects for a bunch of pages at various points.

[sideshowbarker]

@sideshowbarker Is there some kind of 301/302 redirect map in Jekyll? I know we'd set up redirects for a bunch of pages at various points.

We can set up any redirects needed — but for wiki.csswg.org, there are none set up yet. We’d just need to migrate them over from wherever they live now — Apache config file or whatever.

[astearns]

We discussed this as part of #12054 and decided to migrate to https://w3c.github.io/csswg-wiki/.

Two issues I noticed and raised after trying it out today is that edits appear to be requiring a PR from a fork (which I expect is just a setting that can be changed) and that images from the old wiki haven’t carried over yet.

[vivienlacourba]

FYI the DNS change was made and https://wiki.csswg.org/ now points to GitHub Pages servers which serves this new wiki.

[keithamus]

I think we can resoundly call this one closed now. Many thanks to everyone involved!