Migrate website to docusaurus

Sobeston commented 10 months ago

This PR should fix a lot of issues people have been having with the front-end for a long time, introduce the machinery needed for internationalisation, and open the door for further improvements.

Visual comparison (before/after)

TODO

[ ] finish moving all testable zig code from inside markdown to .zig files
[x] fix automated zig testing
[x] migrate to using a build.zig
[ ] add installation steps for macos & freebsd & others
[ ] make sure each page's \<head> is high quality & detailed
- [ ] accessibility, SEO, and embed testing
- [x] per-page descriptions (?)
[x] better category pages (?)
[x] server-side redirects from old "/chapter-0" style urls to new "/category/getting-started" style (will likely do this with Caddy)
[ ] theming (?)
[x] allow viewing hidden code (?)

Currently known problems

Issues when javascript is disabled:
- Stuck on the default TabItem
- Navbar Logo shows up twice
- Site doesn't seem to respect prefers-color-scheme / stuck on light theme
TabItem default is always "linux", no matter the users' OS
Headings inside TabItems are always shown in the side bar, even when not selected, resulting in duplicates on the installation page
~~non-functioning previous/next buttons at the category boundary~~
macos installation steps are a stub
some code blocks don't show up in reader mode on firefox :thinking:

Sobeston commented 10 months ago

Got this branch live at https://zig.guide at the moment

expikr commented 10 months ago

Are content PRs on hold until this is complete?

Sobeston commented 10 months ago

Are content PRs on hold until this is complete?

Yes for now, I may get back to content PRs if this is ongoing for a while

Atomk commented 10 months ago

It looks like contributing will be a little more complicated but the UX seems much better, so thanks for working on these improvements.

Some notes:

To test Zig code, what's the advantage of moving the code blocks to separate files? Maybe the setup is a bit more complicated but code blocks in all pages could also be extracted temporarily at build time, reduces the amount of files lying around and keeps the code and explanations close to each other when editing. I believe the Zig language reference is built with a similar approach.
Some file names contain the pipe character |, that's not allowed on Windows and will result in errors when trying to clone the repo.
For the filename prefix consider using the numbering 01 02 03 [...] instead of 1 2 3 [...] like Ziglings does, so the files are sorted by name correctly.

expikr commented 10 months ago

Btw the site is defaulting the light theme no matter your device preference.

Sobeston commented 10 months ago

To test Zig code, what's the advantage of moving the code blocks to separate files?

I just felt that this is easier at this time, could go back on this later.

Some file names contain the pipe character |, that's not allowed on Windows and will result in errors when trying to clone the repo.

Thanks, just pushed a fix to replace that character

For the filename prefix consider using the numbering 01 02 03 [...] instead of 1 2 3 [...] like Ziglings does, so the files are sorted by name correctly.

Didn't notice this problem because I was viewing the files in vscode, which orders them nicely either way. Updated.

Sobeston commented 10 months ago

Btw the site is defaulting the light theme no matter your device preference.

Pushed a small fix for this, it should now respect prefers-color-scheme. This weirdly doesn't seem to work with javascript disabled, will have to look into that at another time. (I'm fine with a few small regressions for people who disable javascript for the time being)

Sobeston / zig.guide