It has been reported (at least by @ZaidMade and @AntonioND) that the stylesheet needs to be reworked. (The former forked the site, though it's broken due to #15.)

• Noisy background
• Hard-to-read font (in monospace)
• Improvable color scheme (debatable?)

Suggested fixes:

• Background:
  • Use solid color
  • Use solid color behind text only
• Font:
  • Put Roboto in front
  • Use a different font?
• Color scheme:
  • Different navbar? See the fork linked to above
  • Change links colors?

This ticket tracks the progress of migration of the RGBDS project website to a React based stack (Docusaurus).

Currently, the work is being done in this repository, which is being built at https://gbdev.io/rgbds-www2/. Anybody is invited to give feedback or join the development there.

Why:

• Easier to maintain and more streamlined build process
• More attractive site design with less burden on our side
• Extensible in any part with React
• Multi version docs website
• Easy theming (a dark one is already supported)

The plan is to

• Reach the feature parity with the current version
• Ensure every old "mandocs" link points to the correct resources in the website
• Archive the code here (either in an archived repository or in another, frozen and protected branch of the same repository).

Examples:
LDH [C], A
LD [HL], r8

The documentation includes symbols that aren't explained. For example, it's assumed that the reader will know what square brackets indicate. This knowledge should be readily available. I suggest adding a couple thoroughly-explained examples below the legend which cover each of the different syntax for the documentation. You could call it "Comprehending this document" or something.

Going to #breadcrumbs works, but that seems weird.

Should it be #cc8, #ccccc8, or what?

On the main page (https://rgbds.gbdev.io/), near the bottom, under "More", there's a link with the text "Game Boy Development resources" leading to https://gbdev.io/list.html#introduction, which is a broken link. Maybe it should link to https://eldred.fr/gb-asm-tutorial/resources.html instead?

I was just looking at the OP code reference and the wordings are, let's say, quite interesting. Someone changed the documentation to include meme references (see screenshot below). I searched for some strings in the repo, but couldn't find any matches, so I'm guessing some funny guy changed the HTML files on the server. It's very funny and all, but it's quite distracting. Can it be changed back?

Some tables in the RGBASM language description are too large, and cause overflow that breaks the page layout.

A content fix isn't the way to go, as I would prefer not to touch the previous versions' pages.

We modify a bit the mandocs.css distributed upstream with the mandoc package:

• to scope some of the rules inside the manual-text classes, so they don't get applied to all the website
• to remove some of the properties (e.g. font-face, width) so the website themes one get used

We should script this so we can pull upstream a recreate our version without a human intervention

Since the upstream source of the actual content is from the mandocs in the main repository, "edit page" / contribute links should not point to their rendered versions here. We should rewrite them to point to the real sources (or just don't show those).

This should also made clear in the Contributing guidelines.

A README file, quickly explaining the steps needed to build and deploy the website, how the documentation is included (how different versions are handled, etc) is very much needed.

• Add og:title and og:description to homepage and articles
• Add twitter specific tags for generating the cards

E.g. when we'll be on Debian, mention Debian and Arch/AUR

According to the documentation for the GBZ80 instructions that is currently online:

• RRA fills the 8th bit with the value of the carry flag (aka: C -> [7 -> 0] -> C)
• RRCA fills the bit with a zero (aka: 0 -> [7 -> 0] -> C)

However, according to what I am seeing when I actually assemble some code, the opposite is true:

• RRA fills the 8th bit with a zero (aka: 0 -> [7 -> 0] -> C)
• RRCA fills it with the carry flag (aka: C -> [7 -> 0] -> C)

I am not sure if I am missing something here, or whatever, but I thought I would bring it to your attention.

See: #60

This would be useful to check 404s on the site, and possibly more.

See https://github.com/gbdev/rgbds/actions/runs/3170528335

mandoc is able to produce PDF exports, so we should be able to serve those as well. They've been requested a couple times.

As we're now publishing the RGBDS container package, the docker option should be mentioned in the Install page

default.scss styles body with text-align: justify;. Browsers aren't good at text justification, and this causes some words to be separated by too much whitespace. Inline style tags interact badly with justification too, causing their contents to be grouped separately. I find the pages easier to read, especially the man docs, with the default left justification.

The current installation instructions are potentially confusing, more so for the users who need the help most (typically Windows ones).

We have a lot of ways to install RGBDS; in no particular order:

• Homebrew on macOS
• Pacman on Arch Linux
• Docker (if you have that installed)
• Building from source...
  • ...using a downloaded .zip or Git clone
  • ...getting prerequisites with your Linux/WSL package manager, macOS brew, or (most complicated) Cygwin
  • ...using make or cmake
    • ...plus more variants for old cmake versions
  • ...and how to add it to PATH for Windows
    • ...with cmd or Powershell
• Using rgbenv (which has its own build instructions)
• Another page on how to use the master development branch...
  • ...building from source (semi-redundant)
  • ...Pacman on Arch Linux
  • ...the CI builds (are these even worth officially promoting? especially given that "We only recommend doing this on Windows", but IMO shouldn't recommend something for Windows users that takes them to a page like this)

I think we should prioritize using the releases published on GitHub (with a separate page for Windows users explaining how to add the new .exe files to their PATH).

Secondly, mention the packaged options for macOS and Arch Linux.

Thirdly, a separate page on how to build from source. This would have sections on how to install the prerequisites (with apt, pacman, brew, Cygwin, etc), get the source (download the .zip or git clone), build (make or cmake), and install (make install or adding to PATH).

Hardware.inc and (depending on maintenance commitments) RGBDS structs should be linked or referenced by the docs, possibly directly in the man docs

The main landing page on https://rgbds.gbdev.io/ does not have links to:

• RGBDS general information
• RGBASM language description
• RGBLINK linkerscript language description
• GBZ80 CPU instruction set description
  While the version specific pages do. And both link to the CLI options. Which for a casual observer will look like the above list of documentation is just absent. I think it should be all or nothing, so provide all documentation, or none and only have documentation in the version specific part of the site.

Each of the pages shows a tooltip for links on mouseover. This is likely useful, but completely unexplained. Some sort of link tooltip legend would be nice.

How could we better ask for help in maintaining (and developing new features) for RGBDS?

Some ideas:

• Add a "Roadmap" page on rgbds-www, linking some epics and having some kind of plans of the biggest next tasks, giving more (potentially) interesting way for people to interact with the development team, express opinions and contribute
• Add an "issues" feed on rgbds-www, highlightining some recent / relevant / handpicked issues for people to start contributing

CMake build type defaults to None. Need to pass -DCMAKE_BUILD_TYPE=Release on the command-line.

https://github.com/gbdev/rgbds-www/blob/master/_installation/source.md (and RGBDS readme)

We could provide alternative styling, for example modifying the font size, providing a dark mode, and disabling text justification (I was told dyslexic people have trouble with it).
Additionally, it should be possible to use prefers-color-scheme to set the default color scheme, for example.

There are two problems:

1. How can we store this information at least during one browsing session? True persistence is probably not worth implementing, but it'd just be frustrating to have to reset these settings for every visit.
2. How do we provide toggles? Adding them to the navbar would increase the clutter, especially on mobile; plus, managing the drop-downs with the collapsed navbar would add complexity...

Problem 1 could be solved using some JS and browser storage, as I've seen some sites do.
For Problem 2, I'm thinking we could add some button at the bottom of the page, that'd open a drop-down/pop-up of toggles?

To fix this, the anchors should be moved up by the navbar's height. The question then becomes how to do this... JS could be used, but not everyone enables JS; we can't use a custom Jekyll plugin because GitHub Pages prevents it; and I didn't find such a plugin among the whitelisted ones.

An alternative would be making the main content scroll within itself, instead of the whole <body> scrolling; I'm however not sure how to achieve that.

This misrepresents hex literals like "0xFF" or "0x143".

(Using a custom font also causes a "flash of unstyled text" as the @font-face loads. I'd recommend listing just standard fonts that come with Windows, macOS, and typical Linux.)

I plan to use a feature added in gbdev/rgbds#1159 in a Game Boy project, and I want to know what to tell contributors who use Windows to install until RGBDS 0.6.2 comes out. I'm having trouble finding on the website how to obtain and install Windows executables of RGBDS master built by a GitHub Actions job.

1. In https://rgbds.gbdev.io/install, under Windows then "Plain" Windows, follow "go here". Broken. This link leads to a nonexistent anchor using-rgbds-master.
2. In https://rgbds.gbdev.io/install, under Windows then "Plain" Windows, follow "use master", then follow "use our CI". Broken. This link leads back to install under a nonexistent anchor using-our-ci.

The correct answer appears to be this: In https://rgbds.gbdev.io/install, follow "using a development version", then scroll down to "Using our CI" and follow "made available on GitHub". Then under "workflow run results", follow the name of the most recent PR with a green check next to master, scroll down to "Artifacts", and then download rgbds-canary-win64.

Aside: The "go here" phrasing for the call to action is deprecated by a W3C article, which claims that noun phrases make the clearest CTA. According to "The problem with 'click here' and 'learn more' links" by Cynthia Marinakos, it slows the reader and creates a feeling of risk. Answers to questions on UX Stack Exchange and Webmasters Stack Exchange explain what an author can do about "here" in links.

The FAQ claims you need to "make sure there is no whitespace (spaces or tabs) before the macro’s name", but foo: MACRO and the new MACRO foo can now both have whitespace before them. The remaining gotcha with whitespace is to try and invoke a macro foo without any leading whitespace.

See https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3

• Requires bash, as DaKnig mentioned in #1002
• Now requires g++ for rgbgfx

It would be nice to support an alternative dark mode.

Apologies if this is not the correct place to report errors on the generated website/documentation.

This is what I'm seeing on the Google Webmaster console for rgbds.gbdev.io:

We are missing a CONTRIBUTING.md file for this repository

Currently, the site assumes that baseUrl is empty, i.e. that the site is at the domain's root. This breaks forks that use different URLs (example).

Note that Jekyll has the relative_url filter for this.

What about adding a "Try" or "Playground" link in the main navbar? (or in the main action buttons in the home page)?

Side question: should we fork rgbds-live?

the website mentions the page rgbasm.5 multiple times, but links to a non existing page rgbds.5/rgbasm.5 which 404s...

Apparently, MSYS2, like Cygwin, basically runs Windows executables from its own prompt; thus, RGBDS can be installed on it by simply placing a copy of rgb*.exe in its bin/ folder.

Mention this in the install instructions, and perhaps add a caveat that Cygwin is fairly slow.