Pan Docs

The single, most comprehensive technical reference to Game Boy available to the public.

Go to https://gbdev.io/pandocs/ to read the document.

Contributing

This is the RFC proposing the change. You're welcome to discuss the development of this project in the Issues and in our various community channels found here.

Contributing is really easy, fork this repo and edit the files in the src directory. Then, you can send your PR.

To deploy Pan Docs locally:

1. Install Rust, mdBook, and Python 3. mdBook powers the book itself, Rust is used for some custom plugins and Python scripts are used to render some images.
2. Install the Python prerequisites (pip3 install -r requirements.txt) If you're doing that in a Python virtual environment, be sure to activate it in the shell that will run the mdbook commands.
3. Clone this repository and run mdBook in the root folder

# Produce a build
mdbook build
# Watch your files and trigger a build automatically whenever you modify a file.
mdbook watch
# Watches the book's src directory for changes, rebuild the book, serve it on localhost:3000 and refresh clients for each change.
mdbook serve

4. The final HTML files are in docs/pandocs/.

Be aware of the following caveats:

• docs/html/ contains only partially processed files and it's also the folder that gets served by mdbook serve, so you will see some unprocessed custom markup if you visit the endpoint exposed by mdbook's development web server. As a workaround, you can manually serve the file in the docs/pandocs/ with any web server (e.g. you can just run npx http-server in the docs/pandocs folder).

• mdbook watch and mdbook serve do not watch for changes to files in the theme/ or custom/ directories (e.g. highlight.js builds, CSS style overrides). You must trigger the build by either restarting the command, or manually changing one of the watched files.

Special markup

Pan Docs uses a custom mdBook preprocessor & renderer to enable some special markup:

Custom Containers

Those mimick Vuepress' custom containers) functionality.

  ::: type HEADING

  Content

  :::

These are rendered as "info boxes".

• type must be tip, or warning.
• HEADING can contain spaces and can be omitted entirely.
• Both ::: lines must be surrounded by empty lines, otherwise they won't be processed.

E.g.

::: tip SCOPE

The information here is targeted at homebrew development.
Emulator developers may be also interested in the [Game Boy: Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf) document.

:::

will render as

Internal links

[VRAM Sprite Attribute Table (OAM)](<#VRAM Sprite Attribute Table (OAM)>)

Since Pan Docs contains a lot of internal references, and getting the actual anchor is somewhat tedious, internal links are given special treatment. Links whose URL simply begins with a hash are eligible; the rest of the (pseudo-)URL is treated as a section name (as plain text), and the link made to point to that section.

Note that the angle brackets are only required if there are spaces in the URL.

In effect, this means that linking to a section is as simple as copy-pasting its name in the URL field, prepending a #, and wrapping everything in <> if the name contains a space.

Syntax highlighting

Syntax highlighting is provided within the browser, courtesy of highlight.js. RGBASM syntax is highlighted via a plugin, but this requires a custom build of highlight.js.

Steps:

1. Clone highlight.js anywhere, and go into that directory.

   You will probably want to target a specific version by checking out its tag.

2. Run npm install to install its dependencies.

3. Within the extras/ directory, clone highlightjs-rgbasm; ensure the directory is called rgbasm, otherwise the build tool won't pick it up.

4. You can work on and make modifications to highlightjs-rgbasm!

5. To make the custom build of highlight.js, within the highlight.js directory, run node tools/build.js -t browser <languages>..., with <languages>... being the list of languages to enable support for. The languages identifiers are the same that you would use for highlighting (```rgbasm, for example).

6. Copy build/highlight.min.js as theme/highlight.js in Pan Docs' source. Alternatively, for debugging, you can use build/highlight.js for a non-minified version, but please don't commit that.

E.g.

$ git clone [email protected]:highlightjs/highlight.js.git
$ cd highlight.js
$ git checkout 10.7.2
$ npm install
$ git clone [email protected]:gbdev/highlightjs-rgbasm.git extra/rgbasm
$ node tools/build.js -t browser rgbasm c
$ cp build/highlight.min.js ../pandocs/theme/highlight.js

License

We assume the content to be in the public domain.