The Book of the Runtime Build Repo

This repository is a fork of the dotnet/runtime, created solely to build the Book of the Runtime using MkDocs and host it on GitHub Pages.

The site provides easy-to-navigate interface with dark and light themes and interactive search functionality.

It is available at https://jurakovic.github.io/runtime/.

Disclaimer:
This is an unofficial documentation site and is not affiliated with Microsoft.
Microsoft and .NET are trademarks of Microsoft Corporation.

Overview

This repo has two main branches:

docs

• contains built docs together with required scripts and files
• created as orphan branch disconnected from all other branches and commits
• set as default branch in this repo

main

• used as documentation source for build
• kept in sync with upstream dotnet/runtime main branch

Files

Dockerfile - defines docker image used for mkdocs build

build.sh - main script, does the docs build and required file modifications before and after build

check.sh - checks for BOTR docs updates in dotnet/runtime repo

commit.txt - tracks last commit used for docs build

mkdocs.yml - mkdocs configuration

Commands

Clone

Treeles clone and sparse checkout are used because we only want /docs/, /.github/, and /* (root) files.
Otherwise hundreds MB of data would be downloaded and checked out on main branch.

git clone --branch docs --filter=tree:0 https://github.com/jurakovic/runtime.git --no-checkout
cd runtime
git sparse-checkout set .github docs
git checkout

Rebase main

Doesn't work with treeless clone. Use GitHub web UI or normal clone.

git clone --branch docs https://github.com/jurakovic/runtime.git
cd runtime

git remote add upstream https://github.com/dotnet/runtime.git

git fetch upstream main
git checkout --track origin/main
git rebase upstream/main

git push

Important

All commands below are run from repo root (cd runtime).

Run site locally

There are many options. Here nginx is used running in docker.

docker run -d --restart always -p 9903:80 -v ./docs:/usr/share/nginx/html --name botr nginx

Browse http://localhost:9903

Pull docker image

docker pull ghcr.io/jurakovic/mkdocs-botr:latest

Build docker image from source

docker build -t ghcr.io/jurakovic/mkdocs-botr:latest .

Build docs

./build.sh

Check for updates

./check.sh

References

MkDocs
https://www.mkdocs.org
https://github.com/mkdocs/mkdocs

Material for MkDocs
https://squidfunk.github.io/mkdocs-material
https://github.com/squidfunk/mkdocs-material
https://hub.docker.com/r/squidfunk/mkdocs-material
https://pypi.org/project/mkdocs-material/

MkDocs Awesome Pages Plugin
https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
https://pypi.org/project/mkdocs-awesome-pages-plugin/

What others say about BOTR

https://www.hanselman.com/blog/the-book-of-the-runtime-the-internals-of-the-net-runtime-that-you-wont-find-in-the-documentation
https://mattwarren.org/2018/03/23/Exploring-the-internals-of-the-.NET-Runtime/
https://news.ycombinator.com/item?id=15346747