panda's tech note

How do I write this note

All the contents of this note is written in markdown format. Markdown documents are compiled using the mdbook tool. They are managed in a git repository, and HTML files are automatically generated right after commits are pushed to the repository.

Here, I summarize the procedure to set up my environment.

Installation of mdbook

Before installing mdbook, you need to install cargo, which is a package manager of rust language. cargo is installed along with rust, so please refer to the installation manual of rust.

After installing rust and cargo, you can install mdbook by the following command.

$ cargo install mdbook

Preparing git repository

We assume the repository is located at /home/panda/repositories/mybook of You need to first login to your server You then move to the repository and initialize the repository (as a bare repository in this example) by the following commands.

$ mkdir -p /home/panda/repositories/mybook
$ cd /home/panda/repositories/mybook
$ git init --bare

Next, let's set up a git hook so that the HTML files are automatically generated when any updates are pushed to the repository. Edit ./hooks/post-update as follows:

## Only master branch is the target
BRANCH=$(git rev-parse --symbolic --abbrev-ref $1)
if [ "$BRANCH" != "master" ];
        echo "Only effective for master branch, but current branch was $BRANCH."

unset GIT_DIR
git -C /var/www/mybook pull
cd /var/www/mybook
mdbook build

exit 0

Then, grant the permission as follows.

$ chmod 0755 hooks/post-update

Preparing the document root of the HTTP server

You also need to prepare the document root of your HTTP serverr for serving the generated contents. In this example, /var/www/mybook is the working directory used for compiling the documents, and /var/www/mybook/book is set up as the document root. The following commands clone the repository as working directory. Note that you need to have a permission to the directory /var/www.

$ cd /var/www
$ git clone /home/panda/repositories/mybook mybook

Getting started

Now, the initial setup is almost completed. You first need to clone your repository to your working machine, initialize your book, and then add the files to the repository. By the following commands, your initial book will be pushed to your repository and compiled into the document root.

$ git clone ssh:// mybook
$ cd mybook
$ mdbook init
$ git add .
$ git commit -m "First commit"
$ git push -u origin master

Now, you can enjoy with markdown and git.