This is a template repository which may be used to start the development of a written book.
We should "develop" books like we develop any software project. Book-as-code is no different. Book development should be tracked in a git repo. Changes to the book should be proposed via Pull Request. Changes to the book should only be merged after a review resulting in a +1. After merge, continuous integration should compile the book and output a PDF as well as other formats. When a new git tag is created, continuous deployment should publish the versioned artifacts to a location (e.g. Github Releases).
This repository originates from the [Pro Git Book](https://github.com./progit/progit2) repository. The resulting hard fork has had all content replaced with example content. It has been enhanced with the ability to add inline text-based diagram sources such as GraphViz and PlantUml.
We are using the AsciiDoc format for the text of the book; here’s an AsciiDoc quick reference.
The tools required for generating the book assume OSX and the bash shell.
Ensure you are using bash, because newer OSX versions default to zsh.
chsh -s /bin/bash
Then restart your shell by exiting the terminal and restarting it.
Install tools dependencies
# Install the Brew package manager for OSX (https://brew.sh/) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" # Install tools necessary for compiling the docs brew install docker-desktop brew install make # If you're not a hardcore vi or emacs user, install atom or vscode brew cask install atom
Configure your ~/.bash_profile, by appending the following using your favorite editor
# Ensure your git settings are customized git config --global user.name "First Last" git config --global user.email [email protected] # Don't forget to add your personal ssh key to the github server to enable SSH git cloning. # If you don't already have an ssh keypair in `~/.ssh` # Then generate one with `ssh-keygen -t rsa -b 4096` # And then add the `~/.ssh/id_rsa.pub` key to your github profile's ssh keys # https://github.com./settings/keys
Activate your new bash settings
source ~/.bash_profile
Clone the repo
git clone [email protected]:dcwangmit01/book-as-code.git
Generate all output formats of this book
cd book-as-code make all
This will create the following output documents in various formats
build/ ├── book-as-code-kf8.epub ├── book-as-code.docx ├── book-as-code.epub ├── book-as-code.html ├── book-as-code.mobi ├── book-as-code.pdf
You may view the Sample PDF Output here.
The best way to develop the book is to edit the book’s asciidoc source files in an editor window, while a live preview is automatically reloaded in a web browser window.
To start the web browser with live preview, run this command:
make develop
This will build the html version of the book in a loop, as well as open a browser to the automatically-reloading html book.