Make an online book that has code that executes as you build your book
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Bookdown - make a technical book in markdown with "live" code examples

When writing technical books or documents, there is always a challenge in keeping the text updated with the example code. In an ideal world, your code is 100% executable and working in the way your writing says it is.

Bookdown is an attempt to remedy that.

You author your text in markdown that has been augmented with special pre-processor tags. These tags can run commands, create & edit files, and even do limited stuff in the browser.

Make a book

> bookdown my-book
«bunch of stuff happens»
> cd my-book
> bundle install
> rake
> open site/index.html


Suppose you want to teach someone about the <h1> tag. You might write this:

The <h1> tag sets text as the top-level heading.

To see it in action, let's create a place to work

!SH mkdir html

Now, create a simple HTML page:

!CREATE_FILE html/index.html
<!DOCTYPE html>
  <head><title>My Page!</title></head>
    This is my page

To set “This is my page” as your header, wrap it in `<h1>` tags:

!EDIT_FILE html/index.html <!-- -->
  "match": "    This is my page",
  "replace_with": [
    "    <h1>",
    "      This is my page",
    "    </h1>"

And now, it's rendered as a header:

!SCREENSHOT "A wild header appears" html/index.html header.png

Bookdown converts the above markdown into standard markdown by processing the directives that start with a !. The result can then be rendered into HTML for viewing on a page.