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/.

Overview

This repo has two main branches:

docs

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

main

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

Files

Dockerfile - defines docker image used for mkdocs build (ensures virtually the same environment regardless of machine used for build)

build.sh - does the docs build and all heavy lifting

check.sh - checks for docs updates in upstream 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/ 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
cd runtime
git sparse-checkout set docs

Rebase main

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

git fetch upstream main
git checkout main
git rebase upstream/main

git push

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

Create docker image

docker build -t mkdocs-botr .

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

MkDocs Awesome Pages Plugin
https://github.com/lukasgeiter/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