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 with one of:

# 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 git@github.com:highlightjs/highlight.js.git
$ cd highlight.js
$ git checkout 10.7.2
$ npm install
$ git clone git@github.com:gbdev/highlightjs-rgbasm.git extra/rgbasm
$ node tools/build.js -t browser rgbasm c
$ cp build/highlight.min.js ../pandocs/theme/highlight.js

Folder structure

.
├── .github/
│   ├── worflows/
│   │   └── ...
│   └── ...
├── custom/
│   └── ...
├── historical/
│   └── ...
├── mediawiki-exporter/
│   └── ...
├── preproc/
│   └── ...
├── renderer/
│   └── ...
├── src/
│   ├── imgs/
│   │   └── ...
│   ├── SUMMARY.md
│   ├── *.md
│   └── ...
├── theme/
│   └── ...
├── .gitignore
├── Cargo.lock
├── Cargo.toml
├── LICENSE
├── README.MD
├── book.toml
└── requirements.txt

• .github/ - Metadata files related to GitHub.
  • workflows/ - CI workflow description files.
• custom/ - Custom files added to the build.
• historical/ - Archive of legacy Pan Docs versions.
• mediawiki-exporter/ - A script (and support files) to generate this repo's Git history from a MediaWiki export.
• preproc/, renderer/ - Our custom mdBook preprocessor and back-end, respectively. Both are standard Rust project folders (though see Cargo.toml below).
• src/ - The bulk of this repo.
  • imgs/ - Images should go in this folder, for organization purposes.
  • Any .md file mentioned in SUMMARY.md will be rendered to HTML to the output directory.
  • All other files are output verbatim, at the same relative location to src/ (so, for example, images will be output in docs/custom/imgs/).
• theme/ - Files overriding mdBook's default theme/ files.
• Cargo.lock, Cargo.toml - Since preproc/ and renderer/ share most dependencies (transitively through mdbook), this folder is set up as a Cargo workspace. This creates a single target/ directory in the repo's root, containing both crates' dependencies.
• book.toml - The mdBook configuration file.
• requirements.txt - The Python package requirements; see above.

License

We assume the content to be in the public domain.