Why online books?

• Open access

• Open source

• Learn at a deeper level

Software tools used in this tutorial

• Hugo

• VuePress

• Jupyterbook

• R Bookdown

Hugo: Install

• Download binary from Hugo releases; or

• brew install hugo; or

• Refer to official guide for more options

• To check whether installation is successful:

  $ hugo version

Hugo: Quick start

Demosite

$ hugo new site demosite

Theme

The gallery of all available themes can be found here.

$ cd demosite/themes
$ git submodule add ThemeRepoRUL

• Copy all the content within themes/YourChosenTheme/exampleSite and paste it to the root directory of demosite

Hugo: Building and local servering

Configure the config.toml first to make sure that in theme = "ThemeNmae", ThemeNmae is the same as the folder name of themes/YourChosenTheme. Then

hugo server -D

Open http://localhost:1313/ and you should be able to see the site.

Hugo: Content structure

The key to a book is the structure and order of its files. In Hugo, you can set the order via weight = n:

├── _index.md  # ---> weight: 1 
├── chapter01  
│   ├── _index.md  # ---> weight: 10
│   ├── section01.md  # ---> weight: 11
│   └── section02.md  # ---> weight: 12
├── chapter02
│   ├── _index.md  # ---> weight: 20
│   ├── section01.md  # ---> weight: 21
│   ├── section02.md  # ---> weight: 22
│   └── section03.md  # ---> weight: 23
└── chapter03
    └── _index.md  # ---> weight: 30

Hugo: Publish

Read more details in Hugo's instructions or my tutorial

1. Add a netlify.toml to the root directory of demosite

2. Create a repository on GitHub or other platforms

3. Create a Netlify account

4. Create a New Site

5. Build and Deploy

VuePress: Install & Quick start

Prerequisite: Node.js or Yarn classic

Read the official guide for more details.

$ mkdir vuepress-starter 
$ cd vuepress-starter
$ npm init
$ npm install -D vuepress 
$ mkdir docs  # All of the future content will be put in the folder of docs
$ echo '# Hello VuePress' > docs/README.md
$ mkdir .vuepress

VuePress: Quick start (continued)

Add the following to package.json:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

VuePress: Content structure

The default structure of the book is the same as what you see in your docs folder. Therefore, numbering your files make sure they are in the order you desired:

├── 01-abstract
│   └── README.md
├── 02-motivation
│   └── README.md
├── 03-lit
│   ├── 01-lit-female.md
│   ├── 02-homefield.md
│   ├── 03-efficiency.md
│   ├── 04-ranking.md
│   └── README.md
 ...

VuePress: Navbar and Sidebar

First, create a config.js file inside docs/.vuepress:

$ cd .vuepress
$ > config.js

• Look at the config.js of the example site I created to get a quick idea of configuration.

• Consult VuePress's documentaiton for detailed configuration of Navbar and Sidebar.

• vuepress-plugin-sidebar can be handy if you want to generate the sidebar automatically.

VuePress: Build the site

To serve the site locally, at the root directory of vuepress-starter:

$ npm run docs:dev

VuePress: Publish

1. GitHub: Create a Repo

2. Netlify: New site from Git

3. Netlify: Deploy site

Consult VuePress's official documentation for more options.

Jupyterbook: Install

Prerequisite: Python

You can install Jupyterbook via pip:

pip install -U jupyter-book

Jupyterbook: Quick start

Create a sample book:

jupyter-book create samplebook/

Or git clone the demo site I created:

git clone https://github.com/hongtaoh/olymvis-jupyterbook

Jupyterbook: Content Strucutre

Put all of your content in the root direcory of your book project, and then configure the structure in _toc.yml:

- file: intro
- file: abstract
- file: motivation
- file: 03-lit/index
  sections:
    - file: 03-lit/01-lit-female
    - file: 03-lit/02-lit-homefield
    - file: 03-lit/03-lit-efficiency
    - file: 03-lit/04-lit-ranking
- file: 04-plans/index
  sections:
    - file: 04-plans/01-plans-female
    - file: 04-plans/02-plans-homefield
    - file: 04-plans/03-plans-efficiency
    - file: 04-plans/04-plans-ranking
  ...
  ...

Serve site locally

change directory to the directory one level higher than your book project (e.g., book_project). For example, if the book project is sitting on your Desktop, then

cd Desktop
jupyter-book build book_project/ # Or: jb build book_project/

Open file://Users/my_path_to_book/_build/index.html and you'll be able to see the site. See the output after you run jupyter-book build book_project/ for the exact address of file://....

Jupyterbook: Publish

1. GitHub: Create a Repo

2. Netlify: New site from Git

3. Netlify: Deploy site

   • Leave "Build command" blank

   • "Publish directory": _build/html

Consult Jupyerbook's documentation of Publish your book online for details and more options.

Bookdown: Install

Prerequisite: R, Rstuido, TinyTex (if you need PDF outputs)

You can install Jupyterbook via pip:

install.packages("bookdown")

Bookdown: Quick start

If you want an almost empty demo project, refer to the Get started section of the Bookdown official documentation.

Or you can git clone the Repo of my example site:

git clone https://github.com/hongtaoh/olymvis-bookdown

I am familiar with my example, so I'll use it for illustration.

Bookdown: Content structure

• Each chapter is a stand-alone .Rmd file.

• Start the .Rmd file with a chapter name using # Chapter Name.

• If you don't want a certain chapter to be numbered, use # Chapter Name {-}.

• To make the url of each chapter look decent, you can tag it as # Chapter Name {#WhateverTagYouLike}.

• Each chapter can have sections and subsections, which are set with second/third/fourth/fifth/sixth-level headings. Sections and Subsections can also be tagged.

Read here for more details.

Bookdown: Serve site locally

Open your book_project.Rproj with Rstudio, on the upper-right panel, click "Build" and then click "Build book".

Bookdown: PDF, E-Books, and MS Word outputs

With fewer than 10 lines of LaTeX codes, I was able to generate this not-so-bad PDF output. The MS Word output looks pretty good to me.

You should configure the output formats in index.Rmd and _output.yml. See more details in Chapter 3 Output Formats.

Bookdown: Publish

Publishing through Netlify is an easy method. Create a GitHub Repo and configure Netlify as in 3.6 Publish of Jupyterbook. In the last step of Netlify configuration (i.e., before clicking "Deploy site"), leave the "Build command" blank and use _book as the "Publish directory".

Read Chapter 6 Publishing for more options.