mdbook is a cool alternative to gitbook, built with rust. you don't need to manage any frontend work and besides the configuration at the beginning there is no backend to maintain. Most of the time this is just a shallow promise, but with mdbook I learned: If you know how, you can push a mdbook to production in 20-30 minutes - which is really nice I think. That's why I will share my gained knowledge.
As a complete beginner to rust I had no idea how to set up a rust website with this static site generator. But don't be afraid, you won't need to write rust-code to use this SSG, you don't even need to install rust or cargo or anything related, because you can install mdbook via homebrew or github, as it's available as a precompiled binary that will run natively on your OS - linux, mac and windows.
So, our roadmap looks as follows:
- get up and running with mdbook on our local machine
- connect our local repository with our remote server
- configure that remote server (ubuntu digital ocean droplet)
1. mdbook development environment
First we want to install the binary on our local machine. If you are running macOS (assuming homebrew is installed) run:
$ brew install mdbook
otherwise you can get the fitting binary from the mdbook github page:
mdbook Releases
e.g. with curl, run (as of March 2019) this code in the right folder /usr/local/bin/:
$ curl -sL https://github.com/rust-lang/mdBook/releases/download/v0.3.5/mdbook-v0.3.5-x86_64-unknown-linux-gnu.tar.gz | tar xz
now, if you run $ mdbook -V in the terminal, you should see the currently installed version.
Next we want to init our project, simply run:
$ mdbook init myfirstmdbook && cd myfirstmdbook
then (inside the newly created directory) run:
$ mdbook serve
Then open http://localhost:3000 and you will already see our newly created book - cool, heh?
Now, to add new sites to your book, customize the file src/summary.md - while mdbook serve is running, it will automagically create the new md-files, ready for you to write.
2. Connect book to remote server
Now we want to connect this project to our remote server! While on master type into terminal
$ git remote add production ssh://YOUR_USER@YOUR_SERVER_IP/var/repo/myfirstmdbook.git
Now his command line instruction deploys to your server (but first we need to setup the server, see below):
$ git push production master
3. Adjusting the Server
I won't go too deep into configuring the basics of the server, I will assume you find your way to set up basic apache/nginx to create repositories inside of var/www/. For more Information, Digital Ocean has very helpful Tutorials.
Installing mdbook on the remote host works the same way as on your local machine, as you need to install the binary.
So e.g. on a Linux Machine use the cURL code from above inside of usr/bin
$ curl -sL https://github.com/rust-lang/mdBook/releases/download/v0.3.5/mdbook-v0.3.5-x86_64-unknown-linux-gnu.tar.gz | tar xz
Ok, so after that is done – on our remote server we also need to install git, (for example inside of the folder /var/repo/). Then, inside of repo/, run:
$ mkdir myfirstmdbook.git && cd myfirstmdbook.git
$ git init --bare
nice to know:
- bare: this is only used on servers. It will create a repo with the sole purpose to receive pushes.
Inside of myfirstmdbook.git find the /hooksfolder and create a file named pre-receive. inside of that file, add:
#!/bin/sh
echo "removing old deployment"
targetdir=/var/www/pathToTargetDir/html
cd $targetdir
rm -rf *
this will remove everything inside of the directory, everytime you push - that way you can get rid of old deployments before a new deployment.
now also create a file named post-receive
Inside here, type:
#!/bin/sh
echo "running deployment"
targetdir=/var/www/pathToTargetDir/html
git --work-tree=$targetdir --git-dir=/var/repo/myfirstmdbook.git checkout -f
cd $targetdir
#!/usr/bin/env mdbook
mdbook build
rm *
rm -rf src/
cp -r book/* .
rm -rf book/
echo "new mdbook build and deployed"
Explaining: this script will be executed whenever a "git push production master" happened. Then this script will move inside of your project-folder and execute an mdbook build. after that it will remove all the files (not directories) and move everything from the subdirectory /book/ (where the static site lies) one level up, so that only the static site is left.
These two files now also need to be able to execute on your server. Inside of /hooks run:
$ sudo chmod +x post-receive
$ sudo chmod +x pre-receive
Et Voilà. Now you should be able to deploy your mdbook to production running
$ git push production master on your local machine. :)
Top comments (5)
I think that you're overcomplicating the deployment a little. Mdbook generates the entire book as static html, which you can then send to the server using sftp/ftp/scp/rsync. Any of the above and a few more besides. There's no need to even have git or mdbook on the production server if you just push the rendered pages directly.
Other than that, nice article about a really nice tool.
Can I use this with python
Hi Muhammad,
mdbook is a compiled binary. Means: You don't need to install Python or Rust to use it.
Hope that helps.
Yup What i meant to say was that can i run python code snippets
A really nice article you made Sina. Thanks for sharing.