Add bootstrap info to website

_data/navigation.yml

@@ -28,6 +28,8 @@ docs:
         url: /docs/common_commands
   - title: Advanced Features
     children:
+      - title: "Bootstrap"
+        url: /docs/bootstrap
       - title: "Alternate Files"
         url: /docs/alternates
       - title: "Encryption"

_docs/035_common_usage.md

@@ -53,6 +53,10 @@ about [encryption](encryption) for more details.
 only list the files (without decrypting them). Read about
 [encryption](encryption) for more details.
 
+<i class="fa fa-fw fa-asterisk" aria-hidden="true"></i> `yadm clone --bootstrap <URL>`
+: Clone the repository from `<URL>`, and automatically run bootstrap if
+successful. Read about [bootstrap](bootstrap) for more details.
+
 <i class="fa fa-fw fa-git-square" aria-hidden="true"></i> `yadm remote -v`
 : Display detailed information about all configured remote repositories.
 

_docs/037_bootstrap.md

@@ -0,0 +1,168 @@
+---
+title: "Bootstrap"
+permalink: /docs/bootstrap
+---
+
+Often there is more to set up once your dotfiles repository has been cloned. For
+example, if your repository has submodules, you may wish to initialize them. On
+MacOS, you may wish to install **Homebrew** and process a `.Brewfile`. These types
+of additional steps are generally referred to as "bootstrapping".
+
+Though everyone may have a different set of bootstrap operations they need to
+perform, **yadm** has a standard command for executing them.
+
+    yadm bootstrap
+
+This command will execute the program named `$HOME/.yadm/bootstrap`. You must
+provide this program yourself, and it must be made executable. But those are the
+only constraints.
+
+After **yadm** successfully clones a repository, if there is a bootstrap program
+available, it will offer to run it for you.
+
+    Found .yadm/bootstrap
+    It appears that a bootstrap program exists.
+    Would you like to execute it now? (y/n)
+
+You can prevent this prompting by using the `--bootstrap` or `--no-bootstrap`
+options when cloning.
+
+It is best to make the logic of your bootstrap idempotent—allowing it to be
+re-run in the future when you merge changes made on other hosts.
+
+## Examples
+
+Curious about the possibilities? See some examples below. These are all written
+in Bash, but you can use any executable file as a bootstrap.
+
+### Initialize submodules
+
+If you've added repositories as submodules for the **yadm** repository, you can
+initialize them after a successful clone.
+
+```bash
+#!/bin/bash
+
+echo "Init submodules"
+yadm submodule update --recursive --init
+```
+
+### Install [Homebrew](http://brew.sh/) and a bundle of recipes
+
+```bash
+#!/bin/bash
+
+system_type=$(uname -s)
+
+if [ "$system_type" = "Darwin" ]; then
+
+  # install homebrew if it's missing
+  if ! command -v brew >/dev/null 2>&1; then
+    echo "Installing homebrew"
+    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+  fi
+
+  if [ -f "$HOME/.Brewfile" ]; then
+    echo "Updating homebrew bundle"
+    brew bundle --global
+  fi
+
+fi
+```
+
+### Configure [iTerm2](http://www.iterm2.com/) to use your configuration
+
+```bash
+#!/bin/bash
+
+system_type=$(uname -s)
+
+if [ "$system_type" = "Darwin" ]; then
+
+  # possibly add something here to ensure iTerm2 is installed using Homebrew
+  # cask like in the previous example
+
+  if [ -d "$HOME/.iterm2" ]; then
+    echo "Setting iTerm preference folder"
+    defaults write com.googlecode.iterm2 PrefsCustomFolder "$HOME/.iterm2"
+  fi
+
+fi
+```
+
+### Compile a custom terminfo file
+
+```bash
+#!/bin/bash
+
+if [ -f "$HOME/.terminfo/custom.terminfo" ]; then
+  echo "Updating terminfo"
+  tic "$HOME/.terminfo/custom.terminfo"
+fi
+```
+
+### Update the **yadm** repo origin URL
+
+You might initially clone your repo using `https`, but ssh configurations may be
+available after cloning. If so, you could update the **yadm** repo origin to use
+`ssh` instead.
+
+```bash
+#!/bin/bash
+
+echo "Updating the yadm repo origin URL"
+yadm remote set-url origin "git@github.com:MyUser/dotfiles.git"
+```
+
+### Install [vim](http://www.vim.org/) plugins managed with [vim-plug](https://github.com/junegunn/vim-plug)
+
+**vim-plug** can be used in your `.vimrc` to enable plugins. The example here will
+automatically download **vim-plug** and run the `:PlugInstall` command if
+**vim-plug** is missing when **vim** starts.
+
+```vim
+" download vim-plug if missing
+if empty(glob("~/.vim/autoload/plug.vim"))
+  silent! execute '!curl --create-dirs -fsSLo ~/.vim/autoload/plug.vim https://raw.github.com/junegunn/vim-plug/master/plug.vim'
+  autocmd VimEnter * silent! PlugInstall
+endif
+
+" declare plugins
+silent! if plug#begin()
+
+  Plug 'airblade/vim-gitgutter'
+  Plug 'c9s/perlomni.vim', { 'for': 'perl' }
+  Plug 'ctrlpvim/ctrlp.vim'
+  Plug 'vim-syntastic/syntastic'
+  Plug 'yggdroot/indentLine'
+
+  " ignore these on older versions of vim
+  if v:version >= 703
+    Plug 'gorodinskiy/vim-coloresque'
+    Plug 'jamessan/vim-gnupg'
+  endif
+  if v:version >= 704
+    Plug 'vim-pandoc/vim-pandoc-syntax'
+  endif
+
+  call plug#end()
+endif
+```
+
+You can enhance this scheme by having your bootstrap program initialize
+**vim-plug** when you clone, instead of when you first run **vim**. This example
+will install any new plugins, and also remove any plugins now deleted from your
+`.vimrc`.
+
+```bash
+#!/bin/bash
+
+if command -v vim >/dev/null 2>&1; then
+  echo "Bootstraping Vim"
+  vim '+PlugUpdate' '+PlugClean!' '+PlugUpdate' '+qall'
+fi
+```
+
+---
+
+_If you have suggestions for useful bootstrapping logic, let me know..._

_docs/060_faq.md

@@ -94,6 +94,17 @@ like the rest of your dotfiles).
 
 [This page](examples) contains some examples.
 
+## Bootstrapping
+
+### Do I need to write my bootstrap in Bash?
+
+No. Any executable file can be used as a bootstrap. It's up to you to decide
+what works best.
+
+### I've created a bootstrap program. Should I add that to my repository?
+
+Absolutely. That will allow your bootstrap program to be executed each time you
+clone your repository. Read [bootstrap](bootstrap) for more details.
 
 ## Encryption
 

_pages/main.md

@@ -68,6 +68,19 @@ feature_row:
         add such files to an encrypted archive, which can be maintained
         alongside your other configurations.
 
+    '
+  - title: "Bootstrap"
+    alt: ""
+    btn_class: "btn--inverse"
+    btn_label: "Explore how"
+    image_path: "tasks-padding.png"
+    url: "/docs/bootstrap"
+    excerpt: '
+
+        Define your own instructions to complete your dotfiles installation.
+        If provided, **yadm** can execute your custom program immediately
+        following a successful clone.
+
     '
   - title: "FAQ"
     alt: ""