This document will explain you how to set up a local copy of Pan Docs.
# Start by cloning the repository
git clone https://github.com/gbdev/pandocs.git
# and moving to the pandocs directory
cd pandocs
If you have Docker installed, you can pull and use the provided image by running:
docker run -p 8001:8000 \
--mount "type=bind,source=$(pwd)/custom,target=/code/custom" \
--mount "type=bind,source=$(pwd)/preproc,target=/code/preproc" \
--mount "type=bind,source=$(pwd)/renderer,target=/code/renderer" \
--mount "type=bind,source=$(pwd)/src,target=/code/src" \
--mount "type=bind,source=$(pwd)/theme,target=/code/theme" \
-it ghcr.io/gbdev/pandocs
That's it! Pan Docs is live at localhost:8001.
Be aware of the following caveat:
- The locally running site will not update from changes to files in the
theme/
orcustom/
directories (e.g. highlight.js builds, CSS style overrides). You must trigger the build by manually changing a file in thesrc/
directory.
If you prefer to build the image yourself:
docker build -t pandocs .
If you prefer to install every dependency locally:
- Install Rust, mdBook, and Python 3 (3.9 or an earlier version). mdBook is the tool rendering the documentation, Rust is used for some custom plugins and Python scripts are used to render some images. E.g.:
# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install mdbook using cargo
cargo install mdbook
# Remember to add cargo bin directory to your path
# Install Python; e.g. on Debian-based systems:
apt install python3
# Create and activate a virtualenv
python -m venv env
source env/bin/activate
# Install python dependencies
pip install -r requirements.txt
# Be sure to keep this virtual env activated for the following steps
- 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
- 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 bymdbook serve
, so you will see some unprocessed custom markup if you visit the endpoint exposed by mdbook's development web server (:3000).As a workaround, you can manually serve the file in the
docs/pandocs/
with the web server of your choice (e.g. you can runpython3 -m http.server
from thedocs/pandocs
folder). -
mdbook watch
andmdbook serve
do not watch for changes to files in thetheme/
orcustom/
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.
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:
-
Clone
highlight.js
anywhere, and go into that directory.You will probably want to target a specific version by checking out its tag.
-
Run
npm install
to install its dependencies. -
Within the
extras/
directory, clonehighlightjs-rgbasm
; ensure the directory is calledrgbasm
, otherwise the build tool won't pick it up. -
You can work on and make modifications to
highlightjs-rgbasm
! -
To make the custom build of
highlight.js
, within thehighlight.js
directory, runnode 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). -
Copy
build/highlight.min.js
astheme/highlight.js
in Pan Docs' source. Alternatively, for debugging, you can usebuild/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
.
├── .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 the GitHub repository.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 seeCargo.toml
below).src/
- Markdown text sources for the document. You are probably interested in this folder.imgs/
- Images should go in this folder, for organization purposes.- Any
.md
file mentioned inSUMMARY.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 indocs/custom/imgs/
).
theme/
- Files overriding mdBook's defaulttheme/
files.Cargo.lock
,Cargo.toml
- Sincepreproc/
andrenderer/
share most dependencies (transitively throughmdbook
), this folder is set up as a Cargo workspace. This creates a singletarget/
directory in the repo's root, containing both crates' dependencies.book.toml
- The mdBook configuration file.requirements.txt
- The Python package requirements; see above.