Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Migrate website to docusaurus #197

Merged
merged 20 commits into from
Jan 7, 2024
Merged

Migrate website to docusaurus #197

merged 20 commits into from
Jan 7, 2024

Conversation

Sobeston
Copy link
Owner

@Sobeston Sobeston commented Nov 11, 2023 •
edited
Loading

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)

image

image

TODO

  • finish moving all testable zig code from inside markdown to .zig files
  • fix automated zig testing
  • 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
    • per-page descriptions (?)
  • better category pages (?)
  • server-side redirects from old "/chapter-0" style urls to new "/category/getting-started" style (will likely do this with Caddy)
  • theming (?)
  • 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 馃

@Sobeston
Copy link
Owner Author

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

@expikr
Copy link

expikr commented Nov 12, 2023

Are content PRs on hold until this is complete?

@Sobeston
Copy link
Owner Author

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
Copy link

Atomk commented Nov 13, 2023 •
edited
Loading

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
Copy link

expikr commented Nov 13, 2023

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

@Sobeston
Copy link
Owner Author

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
Copy link
Owner Author

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 Sobeston mentioned this pull request Dec 29, 2023
Closed
@Sobeston Sobeston marked this pull request as ready for review January 7, 2024 00:37
@Sobeston Sobeston merged commit 3a7e7e1 into master Jan 7, 2024
This was referenced Jan 7, 2024
Closed
Closed
Closed
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@Sobeston @expikr @Atomk