middlemac 2.0.0 → 3.0.0

data/documentation_project/Contents/Resources/en.lproj/030_get_started/020_your_first_help_book.html.md.erb

@@ -0,0 +1,374 @@
+---
+title:  Your First Help Book
+blurb:  This walkthrough takes you through the quick process of creating
+        and composing your very first Help Book. Along the way you’ll touch
+        upon most of the skills that you need to be successful on larger
+        projects.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+
+<% helpbook_task "first_project_01", "Install a (nearly) empty project template" do %>
+
+After [setting up _Middlemac_][set_up_middlemac], you’re ready to to start
+**Your First Help Book** project. From within your **Terminal** application,
+make sure you’re in the directory of your choice. You will instruct
+_Middlemac_ to create a starter project in this location. Then:
+
+~~~ bash
+bundle exec middlemac init
+~~~
+
+In theory, `middlemac init` should be enough, but prefixing Ruby binaries with
+`bundle exec` ensures that the environment is correctly set up to handle any
+dependencies.
+{: .note .callout}
+
+Feel free to `cd` into the newly created `middlemac-init/` directory, and have
+a look around. Or browse its contents in **Finder**. You’re free to rename
+this directory to something meaningful, but we’ll refer to it by its current
+name throughout this tutorial.
+![Contents of middlemac-init folder][get_started_init_contents]
+
+You should notice fairly quickly that the directory contents resemble that of
+a typical Apple bundle format. The paths `Contents/Resources/en.lproj/` and
+`Contents/Resources/Info.plist.erb` are standard bundle contents, after all,
+other than that strange `.erb` file type added to `Info.plist`.
+
+In this exercise, we’ll be using the `en.lproj/` for our work. The `es.lproj/`
+directory is simply installed as a “quick start” for writing multilingual
+Help Books. If you choose to develop a Help Book for a language other than
+English, then it’s probably safe to change the name of the `en.lproj`, but
+skip ahead to [Localization][localization] to ensure that you name the folder
+properly.
+
+
+<% end %>
+<% helpbook_task "first_project_02", "Examine the Key Project Files" do %>
+
+![Contents of middlemac-init folder][get_started_init_contents]
+
+Have a look at the files above the `en.lproj` level, and the file contents.
+In most cases, you won’t have to make modifications to any of these, other
+than providing your own assets in `SharedGlobalAssets/`, and managing the
+configuration in `config.rb`. This documentation’s **Reference** section
+contains a [full description][directory_reference] of each of these files.
+
+A couple of key points:
+
+- Files with the `.erb` extension are “embedded Ruby”, i.e., they are are
+  Markdown and/or HTML files that have Ruby code which will be executing
+  when serving or building your Help Books. Other than for HTML files that
+  you create, these `.erb` files are used by _Middlemac_ to build you help
+  project. The only thing you have to do with them is not delete them.
+- The `config.rb` file is where you will configure some of the build options,
+  metadata, and target/feature information for your project. For now, simply
+  have a look to become acquainted with it. It’s very well documented.
+- The `makefile` might be used if you care to use **Xcode** for building your
+  Help Books. Feel free to ignore it for now.
+- `SharedGlobalAssets/` includes both assets required by _Middlemac_ to
+  function, as well as a place to put your global, non-localized assets. A
+  more complete description of its contents is elsewhere in this
+  documentation.
+- `Resources/index.html.erb` is the file that runs your entire Help Book.
+  There is little need to modify this file. Your own index file – used as a
+  landing page – exists in the `en.lproj/` directory.
+
+
+<% end %>
+<% helpbook_task "first_project_03", "Examine the Current Help Book Contents" do %>
+  
+This “nearly empty” project does ship with some simple pages used to
+demonstrate how to create sections, nested sections, pages, partials, specify
+page numbers, and other basics. Let’s have a look at these now.
+
+<div style="display: flex; justify-content: space-around;">
+<div style="flex: 0 0 auto;" markdown="1">
+![Contents of en.lproj directory][get_started_init_english]
+</div>
+<div style="padding: 1.5em;" markdown="1">
+Without worrying too much about the other files in the root level of this
+directory, you will notice the `index.html` file. This serves as the root of
+your Help Book, and is often referred to as your “landing page.” Multi-topic
+Help Books usually only have minimal information, such as the application name
+and its logo, on the landing page. Single-topic Help Books, of course, contain
+the entirety of their help content.
+
+You should also notice some other `.html.md.erb` files, prefixed with numbers
+and an underscore. This is one of the two ways that _Middlemac_ lets you choose
+page display order in the navigation system. Similarly, you see at least two
+directories prefixed in the same manner. These directories function as groups
+or sections, and contain files and/or additional group directories for nested
+sections.
+
+These page order prefixes are normally removed when your project is built,
+although you can control this behavior in your `config.rb` file.
+{: .tip .callout}
+
+In the `30_sample_group_number_one/` directory, the `index.html.md.erb` file
+serves as a metadata container _only_; it has `title` [frontmatter][frontmatter]
+that gives a title to the group. The other `.html.md.erb` files, as you can see,
+do not have page order prefixes; instead, they receive their page order via
+their `order` setting in their [frontmatter][frontmatter].
+</div>
+</div>
+
+The `40_sample_group_number_two/` folder contains a nested group, in the
+`01_nested_group_example/` directory.
+
+The folder `asides/` is simply a convenient location to store all of your aside
+files. While it’s not _necessary_ to store them here, doing so has the advantage
+that your aside files do not require the `layout` key in their
+[frontmatter][frontmatter].
+
+Finally, the `assets/` directory contains localized versions of various assets,
+such as [partials][partials], images, etc.
+
+<% end %>
+<% helpbook_task "first_project_04", "Personalize the Project in config.rb" do %>
+
+Let’s personalize the project for your application. If you don’t have a specific
+one in mind now, just invent one. Open the `config.rb` file, and look for the
+line beginning `config[:targets] =`. This is the beginning of your targets’
+configuration.
+
+~~~ ruby
+config[:targets] = {
+        :free =>
+            {
+                :CFBundleID       => 'com.balthisar.middlemac.free.help',
+                :HPDBookIconPath  => 'SharedGlobalArt/free-icon_32x32@2x.png',
+                :CFBundleName     => 'Middlemac',
+                :ProductName      => 'Middlemac',
+                :ProductVersion   => '3.0.0.wip',
+                :ProductURI       => 'http://www.balthisar.com/developer',
+                :ProductCopyright => '© 2018 Jim Derry. All rights reserved.',
+                :features =>
+                    {
+                        :feature_advertise_pro        => true,
+                        :feature_performs_miracles    => false,
+                        :feature_insults_user         => true,
+                        :feature_shows_pink_rectangle => true,
+                    }
+            },
+
+        :pro =>
+            {
+                :CFBundleID       => 'com.balthisar.middlemac.pro.help',
+                :HPDBookIconPath  => 'SharedGlobalArt/pro-icon_32x32@2x.png',
+                :CFBundleName     => 'Middlemac',
+                :ProductName      => 'Middlemac Pro',
+                :ProductVersion   => '3.0.0.wip',
+                :ProductURI       => 'http://www.balthisar.com/developer',
+                :ProductCopyright => '© 2018 Jim Derry. All rights reserved.',
+                :features =>
+                    {
+                        :feature_advertise_pro        => false,
+                        :feature_performs_miracles    => true,
+                        :feature_insults_user         => false,
+                        :feature_shows_pink_rectangle => true,
+                    }
+            },
+
+    } # targets
+~~~
+
+Looking at this data structure, it should be evident that the project is set up
+for two targets: `:free` and `:pro`. This would be appropriate for an
+application that has two versions, such as a “free” version and a “professional”
+version.
+
+The use of multiple targets is optional; you may specify as few as one, or as
+many as you like.
+{: .tip .callout}
+
+Each of these targets is configured with some target-specific data, including
+feature configuration. For example, the product name of the `:pro` target is
+“New Project Pro”, whereas it’s “New Project” for the `:free` target. Similarly,
+when it comes to features, it looks like the `:pro` version supports the
+`feature_performs_miracles` feature, whereas you don’t get that in the `:free`
+version.
+
+Leaving the other fields alone for now, go ahead and personalize **Your First
+Help Book** by changing the `:ProductName`, `:ProductVersion`, `:ProductURI`,
+and `:ProductCopyright` for each of the targets.
+
+This `:targets` structure in Ruby is called a “hash”, which is similar to an
+`NSDictionary` in that it stores key-value pairs. This hash has values for the
+Ruby symbols `:free` and `:pro`. The value of each of these keys is another
+hash, the keys of which define things such as the `:ProductCopyright`. The
+`:features` key of each of these hashes has yet another has as its value.
+{: .note .callout}
+
+
+<% end %>
+<% helpbook_task "first_project_05", "Make changes to the Landing Page" do %>
+
+The landing page is the usually the page that your Help Book first opens to,
+unless your application is providing context-sensitive help, or you arrive
+via a search. By convention, the landing page is the `index.html` file at the
+root of your `.lproj` directory.
+
+In the project, `index.html` is represented by the file `index.html.md.erb`,
+which will become `index.html` when the project is built or served. You should
+already have read that `.erb` signifies an “embedded Ruby” file, but what
+about `.md`?
+
+In _Middlemac_, files are built with various processors according to their
+extensions. In the case of `index.html.md.erb`, the file will be processed as
+embedded Ruby. Next, the `.md` indicates it will be processed as Markdown.
+When there's only a single file extension left – in this case HTML –
+_Middlemac_ knows that it’s done processing, and will output a file of the
+remaining extension type. Similarly, the file `searchTree.json.erb` will
+result in a file `searchTree.json` when your project is built.
+
+Now that you understand why the landing page is named such, go ahead and open
+it for editing.
+
+~~~ erb
+---
+title: Middlemac Project
+categories:
+  - landing
+---
+<%%= md_links %>
+<%%= md_images %>
+This is a (mostly) blank project, and this is its landing page.
+
+There are a few sample groups already set up, and some of the sample pages
+demonstrate the basic features of Apple’s help system and Middlemac’s helpers.
+
+* * *
+
+This project includes a few sample pages in another locale, and as such a
+language selector should be available below, _if_ this page is viewed in a
+browser.
+
+* * *
+~~~
+
+Superficially, it looks pretty spartan; it’s essentially a text file with no
+hints of HTML and something that looks like it _might_ be embedded Ruby. How
+does the minimalistic text become a full featured landing page?
+
+Let’s start with an examination of the top of the file, which is called the
+“frontmatter,” delimited by the `---` at the start and end. The data it
+contains is in YAML format, which is similar to JSON and very legible for
+humans to read. In this case, it should evident that we are providing a
+string for `title` and a single element array for `categories`. These data
+will be used by _Middlemac_ for the construction of your Help Book.
+
+The next two lines, `<%%= md_links %>` and `<%%= md_images %>`, are examples
+of embedded Ruby, in this case, they are used to call “helpers” named
+[`md_links`][markdown_links] and [`md_images`][markdown_images], respectively.
+On this particular page, they’re not being used for anything, but it’s nice to
+know that the features they provide are available should you want them. We can
+ignore these for the time being.
+
+Finally, we arrive at the meat of your page: two paragraphs followed by a
+horizontal rule, followed by another paragraph followed by another horizontal
+rule. This is all determined by the rules for [Markdown][about_markdown],
+which is an easy to read, easy to write, system for converting plain text into
+HTML (in the case of Apple Help Books and _Middlemac_) or any other markup
+language.
+
+If you’re not yet familiar with Markdown, give the 
+[About Markdown][about_markdown] topic a quick review, and then feel free to
+edit the `index.html.md.erb` file with some new Markdown content of your
+choice.
+
+
+<% end %>
+<% helpbook_task "first_project_06", "Make changes to the Copyright Page" do %>
+
+Next, open the `copyright.html.md.erb` file for editing. As before, this file
+contains some frontmatter:
+
+~~~ yaml
+---
+title:  License
+blurb:  License Page
+categories:
+  - copyright
+---
+~~~
+
+This page has a `blurb` key in its frontmatter. You can use this data on your
+own page, if you like, but _Middlemac_ uses this blurb to populate a lot of
+fields that Apple’s help system expects, such as the `navigation.json` file,
+the help indexes, and the `description` meta tag for each page.
+
+Additionally, its `categories` array contains the `copyright` value. This is
+a flag to _Middlemac_ that this page should be treated as the copyright page
+when your Help Book is served to a browser, i.e., this is the page that should
+be linked to from your landing page’s copyright notice.
+
+_Middlemac_ searches for the first page in its sitemap that contains this
+value in its `categories`; if you assign `copyright` to multiple pages, then
+the choice of which page will be used is undefined.
+{: .tip}
+
+Because this page has no page order assigned, neither via a page order as part
+of the filename, nor via an `order` key, it will not be included in the
+navigation menu, and will be excluded from any next/previous page features,
+although you can still link to it manually.
+
+Feel free to practice your elite Markdown skills on this file before
+continuing to the next step.
+
+
+<% end %>
+<% helpbook_task "first_project_07", "A Look at ‹30_sample_group_number_one›" do %>
+
+Open the file `30_sample_group_number_one/index.html.md.erb` As indicated in
+a task above, this file serves only as a metadata container for the group
+within this folder. Looking at its frontmatter, we see:
+
+~~~ yaml
+---
+title:  First Sample Group
+layout: layout-blank
+---
+~~~
+
+When the Help Book builds its navigation structure the title from the group
+is taken from this file’s `title`. But what about the `layout`, and why are
+we specifying what looks like a blank layout with `layout-blank`?
+
+_Middlemac_ uses _layouts_ to describe how `.html.md.erb` files are
+transformed into HTML files. Because these unused `index.html` files _will_
+be included in the final help project, there's the possibility that they
+might be indexed by `hiutil`. The `layout-blank` layout ensures that a 
+meta `robots` tag for these files prohibits indexing, and suppresses any HTML
+body content that might inadvertently be included in the file, such as the
+example that you opened.
+
+Layouts are located in `SharedGlobalAssets/_layouts/`, and you generally don’t
+have to make changes to them if you want to build an Apple Help Book, unless
+you’re looking to automate advanced features not provided by _Middlemac_.
+{: .tip .callout}
+
+Although the sort order of this group is defined by the order prefix on the
+group folder (i.e., `30_`), it could have just as easily been specified using
+an `order` key in this metadata file. In fact, have a look at the
+`page_two.html.md.erb` file: it has no page order prefix, and so its
+frontmatter `order` key specifies its page order within its group.
+
+<% end %>
+<% helpbook_task "first_project_08", "Next Steps" do %>
+
+As you browse the files in this nearly blank project, you should gain an
+understanding of how some of the features of _Middlemac_ are implemented, and
+if not, then don’t worry; that's why this documentation exists.
+
+Feel free to make changes to the existing project to suit your needs and
+taste, and when you’re ready to see the results, move on to the
+[Serve Your Help Book][serve_your_help_book] and 
+[Build Your Help Book][build_your_help_book] topics.
+
+<% end %>
+
+

data/documentation_project/Contents/Resources/en.lproj/030_get_started/030_serve_your_help_book.html.md.erb

@@ -0,0 +1,97 @@
+---
+title:  Serve Your Help Book
+blurb:  Learn how to interact with your Help Book in a live environment using
+        <em>Middleman</em>’s development server.
+---
+<%= md_links %>
+<%= md_images %>
+
+When developing the majority of your Help Book content, it’s likely that you
+will want to view the results in a web browser from time to time, which is
+much faster than building the Help Book, clearing Apple Help Builder’s cache,
+building your application, then running it.
+
+While it’s possible to build your Help Book, and open the individual pages in
+your browser, this isn’t practical for a modern Help Book, which depends on
+AJAX and rewriting paths and other things that a file system doesn’t support,
+despite being static pages.
+
+Instead, you can use _Middleman_’s built-in preview server to host your Help
+Books. It’s a zero-configuration that, quite simply, just works.
+
+Let’s have a look at **Your First Help Book** that you worked on in the
+previous topic. From within that project directory in **Terminal**, simply:
+
+~~~ bash
+bundle exec middleman serve --target pro
+~~~
+
+In just a few seconds, you will see a message indicating that the server is
+running, as well as the address for your site, which is generally something
+like:
+
+~~~ bash
+== View your site at "http://localhost:4567", "http://127.0.0.1:4567"
+== Inspect your site configuration at "http://localhost:4567/__middleman", "http://127.0.0.1:4567/__middleman"
+~~~
+
+If you follow this advice, though, you’re like to see this message in your
+browser:
+
+> ###File Not Found
+
+Remember, this is a macOS bundle, so the content we want is really located at
+`http://localhost:4567/Resources/`. Go ahead and type that into your browser,
+and browse the working Help Book, paying particular attention to whatever
+changes you made in the previous lesson.
+
+When ready, try navigating to this file by copying and inserting into the
+browser address bar.
+
+`/Resources/en.lproj/hello_world_file.html`
+
+You should notice the the browser automatically redirected you to:
+
+`http://localhost:4567/Resources/index.html?localePath=en.lproj#/topic-en.lproj-hello_world_file`
+
+
+## What’s going on here?
+
+Modern Apple Help Books function completely from the `/Resources/index.html`
+file. Every other page in the Help Book is loaded via AJAX by this file, and
+then applied to the current browser window after rewriting paths so that they
+are relative to this `index.html`. Apple’s JavaScript and styles are then
+applied, and then you have a modern Apple Help Book.
+
+Because the help indexer tool, `hiutil`, indexes individual pages, a
+search result would lead to that indexed page, and that indexed page has none
+of Apple’s JavaScripts or styling. So, each page of your Help Book, when
+built, also includes a redirect to the main `index.html`, ensuring that search
+works flawlessly.
+
+During development, troubleshooting sometimes indicates the necessity
+of viewing the HTML file in the browser without this redirect. If you’d like
+to prevent this redirect from happening so quickly during development, have a
+look at the `options.show_debug` option in your `config.rb`.
+
+
+## Specifying Targets
+
+As you may have guessed from earlier, by starting the server with:
+
+~~~ bash
+bundle exec middleman serve --target pro
+~~~
+
+…you’ve started the `pro` target. Because **Your First Help Book** was also 
+configured with a `free` target, you can start it, instead, with:
+
+~~~ bash
+bundle exec middleman serve --target pro
+~~~
+
+You can also start the server with a simple `bundle exec middleman`. The
+action `serve` is _Middleman_’s default, and omitting the `--target` option
+will have _Middlemac_ use the `config[:target]` setting (the default target)
+from your `config.rb`.
+{: .tip .callout}

data/documentation_project/Contents/Resources/en.lproj/030_get_started/040_build_your_help_book.html.md.erb

@@ -0,0 +1,56 @@
+---
+title:  Build Your Help Book
+blurb:  This article shows you how simple it is to build your Help Book, so
+        that it may be included with your Xcode project.
+---
+<%= md_links %>
+<%= md_images %>
+
+When you’re finally ready to build your Help Book, either for including in 
+your application or for hosting on a website, you can do so easily with
+_Middleman_. Let’s build **Your First Help Book** now. In **Terminal** from
+within the project directory:
+
+~~~ bash
+bundle exec middleman build_all
+~~~
+
+Within just a few seconds (depending on the speed of your computer), you
+should find that _Middleman_/_Middlemac_ will have built two, new help 
+bundles: `New_Project_(free).help` and `New_Project_(pro).help`.
+
+_Middlemac_ ensures that no spaces are in help bundle filenames, just in case
+you want to use `make` to build them. The default macOS `make` is
+**GNU Make**, and it simply doesn’t work with paths containing spaces.
+{: .note .callout}
+
+You can `cd` into these bundles in **Terminal**, or use **Show Package 
+Contents** in **Finder** to browse the folders and contents there.
+
+What you should find is a complete, modern Apple Help Book consisting of
+HTML files that you built, as well as all of the supporting `.plist`, `.json`,
+and other files needed to operate the Help Book.
+
+
+## Targets
+
+As with the server, you can specify that _Middlemac_ build a single target,
+rather than all of them. This is accomplished by using the `build` action
+and specifying the `--target` option when invoking _Middleman_:
+
+~~~ bash
+bundle exec middleman build --target pro
+bundle exec middleman build --target free
+bundle exec middleman build
+~~~
+
+That last example builds the default target as defined in your `config.rb`
+file.
+{: .tip .callout}
+
+
+## Add Your First Help Book to your application
+
+If you’re ready to add **Your First Help Book** to your application, then
+skip ahead to [Set Up your Help Project][setup] for information on getting
+your application to recognize your Help Book.

data/documentation_project/Contents/Resources/{Base.lproj/030_skills_refresher/10_markdown_skill.html.md.erb → en.lproj/030_get_started/050_about_markdown.html.md.erb}

@@ -1,27 +1,24 @@
 ---
-title:  Markdown
-blurb:  Although you can hand-write all of your documents in HTML, why not take
-        advantage of the clarity and ease of use offered by Markdown?
-layout: template-logo-medium
+title:  About Markdown
+blurb:  Although you can hand-write all of your documents in HTML, why not
+        take advantage of the clarity and ease of use offered by Markdown?
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
-_Middlemac_ takes care of a lot of the details for generating Apple Help Books,
-and that may be reason enough to use _Middlemac_. However if you decide _not_ to
-use Markdown, then you’re throwing away the single, largest contributor to your
-help file building productivity that there is.
+_Middlemac_ takes care of a lot of the details for generating Apple Help
+Books, and that may be reason enough to use _Middlemac_. However if you decide
+_not_ to use Markdown, then you’re throwing away the single, largest
+contributor to your help file building productivity that there is.
 
 
 What is Markdown?
 -----------------
 
-In the words of the estimable John Gruber (the author of the original Markdown):
+In the words of the estimable John Gruber (the author of the original
+Markdown):
 
 > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
 > you to write using an easy-to-read, easy-to-write plain text format, then 
@@ -35,7 +32,8 @@ the page was written so:
 What is Markdown?
 -----------------
 
-In the words of the estimable John Gruber (the author of the original Markdown):
+In the words of the estimable John Gruber (the author of the original
+Markdown):
 
 > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
 > you to write using an easy-to-read, easy-to-write plain text format, then 
@@ -59,5 +57,5 @@ are all fairly well compatible.
 
 _Middlemac_ uses [_Kramdown_](http://kramdown.gettalong.org/) as its Markdown
 engine because that’s what _Middleman_ uses by default. You can read about all
-its features an syntax on its 
+its features and syntax on its 
 [documentation page](http://kramdown.gettalong.org/documentation.html).

data/documentation_project/Contents/Resources/{Base.lproj/030_skills_refresher/30_middleman_skill.html.md.erb → en.lproj/030_get_started/060_about_middleman.html.md.erb}

@@ -1,15 +1,11 @@
 ---
-title:  Middleman
-blurb:  <em>Middleman</em> is the engine that makes <em>Middlemac</em> possible.
-        It’s critical to know a little bit about this tool.
-layout: template-logo-medium
+title:  About Middleman
+blurb:  <em>Middleman</em> is the engine that makes <em>Middlemac</em>
+        possible. It’s critical to know a little bit about this tool.
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
 _Middleman_ is a [static site generator using all the shortcuts and tools in
@@ -26,7 +22,7 @@ development toolchain.
 Builder _and_ server
 --------------------
 _Middleman_ doesn’t merely build final output; it includes a non-configuration
-server that makes it much easier to develop your website or help book. Features
+server that makes it much easier to develop your website or Help Book. Features
 such as live reload mean that when you change your source file, the site in
 your web browser will update automatically.
 
@@ -40,13 +36,13 @@ Basic concepts
 _Middleman_’s basic concepts are these:
 
 - Organize your site in a source directory that mirrors the desired structure
-  on the server (or in our case, in our help book).
+  on the server (or in our case, in our Help Book).
 - Add file extensions to the source files to indicate the type of pre-processing
   that you want to perform on each of them.
 - Provide the ability to include partials and use helpers to improve your
   content development productivity, while keeping yourself DRY.
 - Provide the ability to use templates and layouts to bring uniformity to your
-  website (in our case, to your help book).
+  website (in our case, to your Help Book).
 - Act as a server in developer mode, building content dynamically as you develop
   it.
 - Build final output, ready to use wherever you need it.
@@ -60,25 +56,25 @@ will actually execute `middleman` to serve or to build your projects.
 
 To start the built-in server in order to preview your work, simply do:
 
-~~~ bash
+~~~
 bundle exec middleman serve --target free
 ~~~
 
 Instructions for accessing the server (the address and port) will be reported to
 you.
 
-Note, too, that `--target` specifies an option; the example about would serve
+Note, too, that `--target` specifies an option; the example above would serve
 the `free` target.
 
 To build the `pro` target, you would do this:
 
-~~~ bash
+~~~
 bundle exec middleman build --target pro
 ~~~
 
 And if you wanted to build every target at once, simply this:
 
-~~~ bash
+~~~
 bundle exec middleman build_all
 ~~~