whatwg / whatwg.org

The WHATWG website and other static resources

This repository hosts whatwg.org and some related sites. Feel free to help improve them!

Code of conduct

We are committed to providing a friendly, safe, and welcoming environment for all. Please read and respect the WHATWG Code of Conduct.

Location of files

Several pages present on https://whatwg.org/ are generated or copied from the whatwg/sg repository. This happens in the deploy.sh script.

So if you're confused as to why the whatwg.org directory doesn't have everything you see on the site, that's probably why.

Acknowledgments

Thanks to Oliver Williams for the most recent home page design (see #90 and #153).

whatwg.org's Issues

Add Loader to idea.whatwg.org

See #98 (comment) by @xfq.

Should biblio.json contain an entry for the WHATWG Wiki?

I'm not sure if anything but the HTML Standard references it, but I noticed WHATWG Wiki is in https://github.com/tobie/specref/blob/master/refs/legacy.json which seems a little wrong. I guess biblio is the best place or do we want to reserve that for Ideas/Standards?

Add .editorconfig and .gitattributes to this repo

Update links and layouts to harmonize with revised structure

Moved from whatwg/sg#49 on behalf of @geoffcr :

I realize that the front page of the WHATWG at https://whatwg.org/ has "history" and is not likely to change, but - to a novice user - there are some confusing elements to how the links are laid out (and some of the terminology). Here are several - some significant, some less so:

Workstreams
Where do I find a list of Workstreams? Oh - Standards; we don't call them "Workstreams" anywhere, so far as I can tell. That should presumably be fixed.
(We also might want to change the "Standards" block to say "See the other Living Standards developed at the WHATWG".)

Policies
Where do I find Policies? Oh - if I click on FAQ, Standards, or Participate, there's also a "Policies" tab at the top. Policies deserve a link from the main page, along with Standards and FAQ. ("Working Mode" has its own front-page button, even though it's now a subset of Policies; perhaps that should be swapped out and replaced with Policies?)

Signing up
"Participate" takes me to a nice narrative page, but please point people to the governing Workstream Policy and IPR Policy in addition to the Code of Conduct and the Working Mode. (This strikes me as significant.)
"Join" takes me straight to the repositories instead of to the participation page. That strikes me as confusing.

IRC
Do people still use IRC? (In other words, does it merit front-page real estate?)

Format
This is just a visual nit, but it's disorienting (to me) to fly from the "Nine Colored Blocks" front page to a "Traditional Tabbed" Standards/FAQ/Policies/Participate page, or to the Living Standards in a cleaner HTML presentation. Not sure what to fix, except perhaps to ensure that there's a consistent relationship between the tabbed pages and the front page.

Review Drafts
Will we see the latest Review Drafts posted on the Living Standard page? For example, https://html.spec.whatwg.org/multipage/ has links to the one-page version, multipage version, developer version, translations, etc. Will there also be a "Latest Review Draft" button? (I would think so; otherwise, non-technical lawyers are going to have a hard time finding it in the repository.)

robots.txt and Internet Archive

Old snapshots of WHATWG specs in the Internet Archive are now blocked by robots.txt. For example, https://web.archive.org/web/20040605213911/http://www.whatwg.org/specs/web-apps/current-work/ says:

Page cannot be displayed due to robots.txt.
See www.whatwg.org robots.txt page.

Could the robots.txt restrictions be relaxed?

Consider renaming files with question marks in them in this repo

The forums.whatwg.org subdirectory contains files which have question marks in their name. Unfortunately it appears that makes Git on Windows totally unusable for this repository.

I've been working around this by using the Windows Subsystem for Linux, but that has some limitations, and e.g. I can't use my usual text editor.

It would be ideal if perhaps we could rename these files to some other filenames (e.g. use __ instead of ?) and then use the server config to map ?s to that other filename.

Automate generating whatwg.org policy pages from whatwg/sg

The script in #132 is used to generate several pages on whatwg.org from Markdown documents in whatwg/sg. We should figure out a way to automate this.

Several possibilities:

1. Build process lives here in whatwg/whatwg.org's Travis job; pushes to whatwg/sg trigger a whatwg/sg Travis job which uses https://docs.travis-ci.com/user/triggering-builds to trigger the whatwg/whatwg.org Travis job.
2. The Travis job for whatwg/sg could do the build, then commit and push the generated output into whatwg/whatwg.org directly, thus indirectly triggering the whatwg/whatwg.org Travis job (which just does a deploy).
3. The Travis job for whatwg/sg pushes a small file containing a commit hash for whatwg/sg into whatwg/whatwg.org, and the whatwg/whatwg.org build process uses whatever hash is committed to build. (A variant on (1).)

I like (1) the most.

Change footer to recommend filing issues on whatwg/meta

Currently it reads

Queries should be directed either to one of our mailing list or to Ian Hickson, who is acting as a spokesman for the group.

Add regular expressions from html-build to build/deploy.sh

That way all standards benefit from the grammar police.

Moved from whatwg/resources.whatwg.org#51.

Unauthenticated use of api.github.com is rate limited; fails on Travis

(moved from the common-build repo that I'm going to delete)

As part of #71 I've seen some branch builds fail mysteriously, and after adding debugging it looks like it was failing in:

SERVICE_WORKER_SHA=$(curl https://api.github.com/repos/whatwg/whatwg.org/contents/resources.whatwg.org/standard-service-worker.js \
                     -H "Accept: application/vnd.github.v3+json" \
                     | grep -Po '(?<="sha": ")[^"]*') # Hacky JSON parsing but works for SHAs

It doesn't always reproduce, but in https://travis-ci.org/whatwg/infra/builds/270176543 I had logging and caught "curl: (22) The requested URL returned error: 403 Forbidden"

Most likely, this is due to rate limiting.

@domenic, before I attempt a fix, can you help me understand the purpose of this service worker freshness check? Is the purpose merely to change the generated service-worker.js in some (any) way if https://resources.whatwg.org/standard-service-worker.js has changed? Why does this make sense to do at build time, given that the standard could be updated much less frequently than standard-service-worker.js?

Move code of conduct here

https://wiki.whatwg.org/wiki/Code_of_Conduct should move to a web page.

Split build/ into its own repository?

AFAICT there's no particular reason that https://github.com/whatwg/whatwg.org/tree/master/resources.whatwg.org/build needs to be deployed to a web server, we could curl it from https://raw.githubusercontent.com/whatwg/whatwg.org/master/resources.whatwg.org/build/deploy.sh.

Given that, should we just put it in a separate repository? whatwg-build? common-build?

@annevk @domenic

Polish validator.whatwg.org

@domenic in #31

For bonus points, replace all reference to "validators" with "conformance checkers" or "checkers", and copy the styling from spec.whatwg.org so that it fits into the main site a bit better.

Give https://spec.whatwg.org/ a heading

Every tab (other than Home) seems to have a heading that equals the name of the tab, except standards.

convert-policy.py loses Markdown links in headers

convert-policy.py loses Markdown links in headers. This doesn't currently affect any WHATWG policy documents, but it would be nice to fix at some point.

Updating description of [email protected]

In particular we should probably mention some of the more valuable ways to participate and mention that the list is primarily meant as a fallback and maybe for announcements. And I suppose whatever purpose people want to use it for that isn't too upsetting to the 1000 or so subscribers.

We should also not write "WHAT Working Group".

Anyone more thoughts?

Trim images/

I am skeptical that CFC, CFI, README, REC, WD, and icon-white have uses. Maybe in some of the obsolete specs in specs/ but they should probably just not have such images.

Original HTML multipage spec links broken - needs redirect fix

Links to the original HTML multipage spec now all redirect to top of the HTML spec all-in-one-page and thus are effectively broken (trying to hunt to find what you thought you were looking for through the entire spec is not reasonable).

There are LOTS of links of the form www.whatwg.org/specs/web-apps/current-work/multipage on the web pointing to specific pages and sections (in email archives etc.) and these really should keep working.

Current behavior: links of the pattern

• http://www.whatwg.org/specs/web-apps/current-work/multipage/abc.html#def
  All redirect to
• https://html.spec.whatwg.org/

Expected behavior: links of the pattern

• http://www.whatwg.org/specs/web-apps/current-work/multipage/abc.html#def
  Redirect to:
• https://html.spec.whatwg.org/multipage/abc.html#def

Specific example:

• http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#other-link-types
  Should redirect to:
• https://html.spec.whatwg.org/multipage/links.html#other-link-types

Build script improvements

I'd like the build script to also report any Bikeshed WARNING and LINK ERROR messages, possibly as fatal. Otherwise we risk introducing subtle issues and letting it all get worse over time. whatwg/fetch#639 is a good example of that happening. Maybe some standards will always have WARNING or LINK ERROR messages, but it seems to me we should not tolerate them. (I actually thought this was fixed for Encoding, but it seems to still happen.)

And in general it should do better with error handling. For FATAL ERROR messages you currently don't see anything and have to run Bikeshed again yourself.

Instead if upon failure we first run curl https://api.csswg.org/bikeshed/ -f -F [email protected] -F output=err -F md-Text-Macro="SNAPSHOT-LINK LOCAL COPY" or some such or store the errors from the initial run directly somehow and then fail the build we'd at least have something to work with.

convert-policy.py gets some stuff in parentheses wrong

Moved from whatwg/sg#45, details there.

Move mailing list related wiki FAQ entries to /mailing-list

Not necessarily in this PR, but I realized that the remaining content of https://wiki.whatwg.org/wiki/FAQ could probably go here.

Make trailing dot domains work

Such as https://whatwg.org./. We should probably redirect them to the version without the dot.

Redo "Join" on the home page

Some thoughts:

• We should do away with redirecting to the mailing lists, in particular the help list is effectively replaceable with a link to stackoverflow.com. I kinda feel we should maybe give up on it altogether, but maybe that's still too soon.
• If we do that, we need a place where new people can go. So maybe a page that lists what you can do as we already have on the wiki (but more up-to-date and with less information). Review standards, work on tests, write standards, go through old issues...
• Ideally once we have "working mode" we can also link to it somehow. New tabbed page?

Redirect various things to resources.whatwg.org

• style/specification
• images/logo*

Would be good to find out if anything is using them and update the links too

Needs a basic README

Change spokesman (on /) to spokesperson and buzzword (on /specs/) to obsolete

Make dfn.js work for multipage HTML

Moved from whatwg/resources.whatwg.org#36

Use file extensions, at least for non-HTML files

Omitting file extensions makes sense for URLs that you paste around, I think. But for image URLs and stylesheet URLs and such, it seems better to actually use the file extensions. Then you can view them using GitHub more easily.

Check in scripts to generate HTML versions of policies from Markdown

Check in scripts to generate HTML versions of policy documents from the Markdown versions in the SG repo.

Prevent robots.txt indexing old specs

Everything in specs, not just the URL snapshot, should ideally not show up in search results

Overlapping text on some pages

The h1 element on some pages (such as spec.whatwg.org, and the 404 page) looks weird:

"The" and "Web" overlaps. It might be caused by this rule:

whatwg.org/src/style/tabbed-pages

Line 20 in 56109a1

.the { display: block; margin: 0 0 -1em 0; font: 100 2em sans-serif; color: silver; }

(the margin declaration)

PNG logos have the wrong color in macOS Chrome/Safari

See #95 (comment). Per https://webkit.org/blog/6682/improving-color-on-the-web/ the problem might be that the images have a color profile? It seems without sRGB would be assumed, which would presumably do the right thing?

Preview feature for whatwg.org PRs

Either we start using mod_rewrite to keep URLs the same but have extensions for local viewing or we need some kind of preview setup to make things easier to review.

n.whatwg.org issues

• The formdata resource is no longer rendered as text/plain.
• The Index listing has ../ as an item.

Remove references to developers.whatwg.org for now

We should still work on getting the developers spec back and running, but until we do, we should not link to it.

Run HTML checker on resources

Although deploy should only happen on commit to master, we should be able to check the HTML (of "active" resources) all the time.

Use alphabetical order on spec.whatwg.org

Let's not play favorites.

Add a page at n.whatwg.org/work

It should link to https://html.spec.whatwg.org/#licensing-works (or the multipage variant) and should clarify that despite web browsers redirecting to https://, for the purposes of the namespace you must use http://.

Run shellcheck on CI for the deploy scripts stored here

cf https://github.com/whatwg/html-build/blob/32835201f72cf4518369065a6c20d2de50369f0c/.travis.yml

Pick a canonical URL between whatwg.org/specs and spec.whatwg.org

I prefer the latter.

Then we should 301 one of them into the canonical one.

Change 404 to recommend filing an issue here instead of emailing Hixie

Update script to make making <h2> and <title>s of documents consistent with the rest of whatwg.org

Update script to make making <h2> and <title>s of documents consistent with the rest of whatwg.org.

This is the script part of whatwg/sg#44

Fetching deploy.sh keeps failing

This is for Fetch's master:

Setting environment variables from .travis.yml
$ export ENCRYPTION_LABEL="e149beb9c312"
$ export DEPLOY_USER="annevankesteren"

$ bash -c 'echo $BASH_VERSION'
4.3.11(1)-release

0.43s$ curl --remote-name --fail https://resources.whatwg.org/build/deploy.sh && bash ./deploy.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  5503  100  5503    0     0  21895      0 --:--:-- --:--:-- --:--:-- 21924
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    87  100    87    0     0    574      0 --:--:-- --:--:-- --:--:--   576

The command "curl --remote-name --fail https://resources.whatwg.org/build/deploy.sh && bash ./deploy.sh" exited with 1.

Done. Your build exited with 1.

Fetch it from https://raw.githubusercontent.com/whatwg/whatwg.org/master/resources.whatwg.org/build/deploy.sh instead? And if we go down that path, no longer host it on resources.whatwg.org as we fetch it from GitHub anyway?

cc @domenic @foolip

Add big obsolete banners to old specs

Everything in specs/ deserves a banner with a link to the correct new place, I believe. Maybe not the url snapshot.

Rename src/ to whatwg.org/

Once whatwg.org moves to the same server idea.whatwg.org is on we could rename src/ to whatwg.org and we could put spec.whatwg.org in its own directory rather than the current setup.

We could then also put some of the redirect and .htaccess logic here for all of the server. Though that depends a bit on how we want to organize all that and where it's best to put it.

Be mobile-friendly

We need a meta viewport tag, and possible some different header/tabbed pages styles

Customize nginx directory listings (e.g., use WHATWG green)

From @sideshowbarker on September 12, 2017 8:50

See #84 (comment). With some minimal CSS, we can customize the styling of nginx directory listings for, e.g., https://resources.whatwg.org/ and https://images.whatwg.org/ and https://n.whatwg.org/

Copied from original issue: whatwg/resources.whatwg.org#64

More clearly mark domintro as non-normative

We're using green boxes with short API descriptions as help for web developers, e.g., https://dom.spec.whatwg.org/#interface-customevent, but they continue to cause some confusion where implementers quote the boxes rather than the normative material.

Instead of "Note" we could use "Introduction (non-normative)" or "For web developers (non-normative)", or maybe there's an even better idea?

cc @fantasai @tabatkins @zcorpan @terinjokes @domfarolino @shuangMoz

Delete status-2008-12?

Seems confusing to keep

Make whatwg.org and spec.whatwg.org available offline via a service worker

I don't think going "full PWA" with a manifest is worthwhile since currently only Chrome uses the manifest and it requires hiding the address bar to get any benefits. (See previous discussions in whatwg/streams#637.)

But a service worker at least would be nice.