Markrundown Sample

_what-is-markrundown.md

NOTE Markrundown now has a working draft implementation to be used with gitbook. See https://github.com/eliotsykes/gitbook-plugin-markrundown

Markrundown can be used to write a technical book that is a step-by-step guide to coding an application.

Markrundown allows you to write the book and the code for the book's example codebase in markdown.

Markrundown is intended for books that need to be regularly updated and rely on having an associated codebase that is stored in a git repo that the reader uses as a reference.

If the book is updated, markrundown will rebuild the book and the book's associated codebase git repo. Each new version of the book is tied to one new version of a git repo. This new git repo has no history from previous versions of the book. The git repo is built entirely from scratch at the same time the book is built from markdown into its output format.

To achive this, Markrundown is dependent on code patches written in the markdown document (you know the patches you get from running git diff).

As the book is processed into its output format, these inlined code patches are applied to a new git repo to build the tutorial codebase patch-by-patch, bit-by-bit, just as the reader who follows your book's steps would build the app step-by-step.

Markrundown fenced code blocks have an info string on the same line as the opening fence. Here's what the keywords mean:

• run - run this code block (in the system shell if its bash too). Used to build the associated codebase for the book, and run tests on the codebase too.
• bash - the code highlighting language is bash and if it has a run on the same line, run it
• hide - hide this code block from the final rendered HTML. Used for code that you need to run to build the book and associated codebase but don't want to show to the reader
• patch - apply this patch to the working directory. Used to build up the associated codebase for the book and show the code changes that a reader will need to make when following along the tutorial steps. patch may need to eventually take extra options for helping with outputting the author's desired content which may be slightly different to what's needed in the patch.

See hello_world.md.txt below for a sample of how a raw markrundown document would look.

hello_world.md.txt

```bash run hide
# The directory the codebase will be built in
mkdir -p build && cd build/
```

# Intro

This tutorial will take you through writing your first Rails app by getting the home page to print a "Hello World" message.

Tutorial prerequisites:

- Ruby 2.2 installed
- Rails 4.2 installed
- Mac OS X
- You're able to use the command-line
- You know git
- You know some Ruby

## Generate Your First Rails App

Generate a new Rails 4.2.3 app using the following command:

```bash run
rails _4.2.3_ new hello-world
```
The above command generates a new Rails app in a directory named `hello-world`.

From now on all of your work and the commands you issue will be from inside your project root directory, so change directories into `hello-world/`:

```bash run
cd hello-world/
```
Rails includes a server command to allow you to test your app in your development environment.

Run the server with this command:

```bash run
bin/rails s
```

This starts a server on port 3000 on your localhost. Visit [http://localhost:3000] in your browser and check you see the Rails default welcome page:

```bash run hide
# Book bin/ directory, not rails app bin/ directory, notice the .. in path:
../bin/welcome_page_screengrab.rb
```
TODO: Somehow base64 inline or reference image generated by above welcome_page_screengrab.rb here. See gitbook existing tools.
<img src="base64....???" alt="Rails Welcome Page">
![Rails Welcome Page](screenshot-output-from-above-command-goes-here-as-.png)

To stop your Rails server, press the two `Ctrl + C` keys together at once.

```bash run hide
CTRL+C # TODO: How to do this in bash script?
```

Start storing your project in a git repository:

```bash run
git init .
git add .
git commit -m "Initial commit"
```

## Custom Home Page

### Edit `config/routes.rb`

Uncomment the `root 'welcome#index'` route in `config/routes.rb`. This is the first step towards customizing your home page:

```patch
diff --git a/config/routes.rb b/config/routes.rb
index 3f66539..92824e8 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -3,16 +3,7 @@ Rails.application.routes.draw do
   # See how all your routes lay out with "rake routes".
 
   # You can have the root of your site routed with "root"
-  # root 'welcome#index'
-
-  # Example of regular route:
-  #   get 'products/:id' => 'catalog#view'
-
-  # Example of named route that can be invoked with purchase_url(id: product.id)
-  #   get 'products/:id/purchase' => 'catalog#purchase', as: :purchase
-
-  # Example resource route (maps HTTP verbs to controller actions automatically):
-  #   resources :products
+  root 'welcome#index'
 
   # Example resource route with options:
   #   resources :products do
```

```bash run
git commit -m "Setup home page route" config/routes.rb
```

### Create `WelcomeController`

To serve the home page you'll need to create a `WelcomeController` class with an `index` action method.

Notice how these names, `WelcomeController` and `index` have similarities with the `root 'welcome#index'` code you uncommented in the previous steps. This is not a coincidence:

- The `welcome` part of `root 'welcome#index'` implies that there is a `WelcomeController` class.
- The `#index` part of `root 'welcome#index'` implies that there is an `index` method in `WelcomeController`.

Create the controller at `app/controllers/welcome_controller.rb` and write this code in that file:

```patch
TODO: Patch to create welcome_controller.rb
```