Docu review done: Mon 06 May 2024 09:56:44 AM CEST

mdbook

Table of Content

General

mdbook is able to create out of markdown files, SUMMARY.md (as controler file) and book.toml (config for wiki) files html files.

This wiki is build fully automated out of a existing git repository which holds the .md file.

The original mdBook documentation

Concept for building this wiki

Setup and Requirements

  • mdbook is available in your $PATH, (installation documentation)
  • Repository holding the doumentaion files .md
  • Repository hodlign configuration for mdbook
  • Trigger/hook for executing update script (gitea webhook used in this case)
    • for catching the push based gitea-webhook we use in this case webhookey
  • A running webserver for ofthering the files

Inside of the mdbook config repository, we have specified the documention repository as a submodule on the direcotry src.

Repo structure

mdbook
/data/mdbook
├── .gitignore
├── .gitmodules
├── book
├── book.toml
├── src
└── update_deploy.sh
docu
/data/mdbook/src
├── SUMMARY.md
├── dir1
│   ├── dokufile1_1.md
│   └── dokufile1_2.md
└── dir2
    ├── dokufile2_1.md
    └── dokufile2_2.md

Update and build script sample

This is a sample who you can automatically build the book and copy the new data to your html path:

#!/bin/bash
mdbook_source="/data/mdbook"
mdbook_source_src="${mdbook_source}/src"
mdbook="/opt/mdbook/mdbook"

echo "1: Updateing mdbook repo"
git -C "${mdbook_source}" pull -q origin master

echo "2: Removing 'old' src dir"
rm -rf "${mdbook_source_src}"/* "${mdbook_source_src}"/.g* >/dev/null

echo "3: Regenerating src dir"
git -C "${mdbook_source}" submodule -q update --init --recursive

echo "4: Updating submodules"
git -C "${mdbook_source}" submodule -q update --remote

echo "5: Rebuilding mdbook"
mdbook build "${mdbook_source}" >/dev/null

echo "6: Updating external directory"
rsync -aP "${mdbook_source}"/book/* /var/www/wiki_mdbook >/dev/null