middlemac 2.0.0

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/10_markdown_skill.html.md.erb

@@ -0,0 +1,63 @@
+---
+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
+---
+<%= 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.
+
+
+What is 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 
+> convert it to structurally valid XHTML (or HTML).
+
+This offers the powerful advantage of having text-based source files that are
+themselves very highly legible. For example, this opening of this section of 
+the page was written so:
+
+~~~ markdown
+What is 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 
+> convert it to structurally valid XHTML (or HTML).
+
+This offers the powerful advantage of having text-based source files that are
+themselves very highly legible. For example, this opening of this section of 
+the page was written so:
+~~~
+
+As you can see, it’s highly legible and uses a lot of the same text formatting
+idioms with which you are doubtlessly already aware.
+
+
+Markdown Syntax and Engine
+--------------------------
+
+There are several “flavors” of Markdown, but they all adhere to John Gruber’s
+original as a base line and extend it in various ways. For the most part, they
+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 
+[documentation page](http://kramdown.gettalong.org/documentation.html).

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/20_frontmatter_skill.html.md.erb

@@ -0,0 +1,54 @@
+---
+title:  Front Matter
+blurb:  <em>Middleman</em> (and hence <em>Middlemac</em>) source files use
+        front matter to control many features of pages.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Front matter is a document header section that contains key-value data that
+applies to a page. This data can be referred to later for output or control.
+For example, the title of this page was specified with a `title:` key in the
+source document’s front matter, and its layout was specified with a `layout:`
+key.
+
+Front matter can also control page order (a feature of _Middleman_’s
+`middleman-pagegroups` gem), inclusion of pages for targets/features (provided
+by the `middleman-targets` gem), and more.
+
+Here’s this document’s front matter:
+
+~~~ yaml
+---
+title:  Front Matter
+blurb:  <em>Middleman</em> (and hence <em>Middlemac</em>) source files use
+        front matter to control a lot of features of pages.
+layout: template-logo-medium
+---
+~~~
+
+## Declaring Front Matter
+
+Front matter is defined as being delimited at the beginning and end with a line
+consisting of a series of three hyphens (`-`), and this block must appear at the
+top of a document.
+
+Although specific front matter keys are discussed elsewhere in this
+documentation it’s worth pointing out that the `title:` and `:blurb` are used
+extensively in _Middlemac_. For example all of the automatic navigation
+features are built using this data, meaning that this data need only appear
+once, here, in this very document.
+
+## Markdown in Front Matter
+
+You may have noticed that the front matter contains HTML. Because the front
+matter consists of data rather than content specifically targeted for display,
+it is not processed by the Markdown engine. Front matter is one of the very
+few places in a _Middlemac_ project where you have to revert to using HTML.
+

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/30_middleman_skill.html.md.erb

@@ -0,0 +1,93 @@
+---
+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
+---
+<%= 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
+modern web development](http://middlemanapp.com). It was intended to have been
+a tool to create static websites with most of the dynamism of websites running
+on technologies such as PHP and Ruby on Rails. Static websites are fast and
+secure.
+
+Apple Help Books, in their essence, are static websites. 
+
+_Middleman_ with the help of _Middlemac_ is the perfect tool in your help file
+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
+such as live reload mean that when you change your source file, the site in
+your web browser will update automatically.
+
+The server captures changes to most of your source files. However in certain
+circumstances you may have to restart the server to recognize certain changes,
+such as new directories in your source code.
+
+
+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).
+- 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).
+- Act as a server in developer mode, building content dynamically as you develop
+  it.
+- Build final output, ready to use wherever you need it.
+
+
+Using _Middleman_
+-----------------
+
+Because _Middlemac_ is an extension to _Middleman_, it’s worth noting that you
+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
+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
+~~~
+
+
+More about _Middleman_
+----------------------
+
+If you stick to the conventions it’s not necessary to become an expert in
+_Middleman_. However as you grow your skills you may want to consider using
+some of its more advanced features or even add your own extensions. You can
+access _Middleman_’s full documentation on its
+[documentation website](https://middlemanapp.com/basics/install/).

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/40_ruby_skill.html.md.erb

@@ -0,0 +1,67 @@
+---
+title:  Ruby
+blurb:  As the language that powers <em>Middlemac</em>, it’s worth taking a
+        short look at the Ruby language.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+[Ruby](https://www.ruby-lang.org/en/) is the language that _Middlemac_,
+_Middleman_, and many of the others tools are written with. You do not have to
+learn Ruby to take advantage of _Middlemac_, although some ability to work with
+it will be invaluable to you.
+
+Ruby may surprise you
+---------------------
+
+If you’re a software developer, then it’s highly likely that you will be able to
+read most Ruby code immediately. Coming from an Objective-C or Swift background,
+these are a few things that may surprise you.
+
+### Symbols
+Ruby has a type of identifier called a `symbol`. They are used quite extensively
+and look like `:this_symbol`. As identifiers and not variables, you can’t assign
+values to them. Their value is themselves, though they have useful string
+representations (`:this_symbol.to_s`). You can even get the symbol
+representation of `'this_string'.to_sym`. Because they're unique, they make
+excellent array/hash keys and excellent, guaranteed unique values.
+
+### Everything is an object
+Everything is an object, including what are fundamental datatypes in other
+languages. Need to convert the integer `i` to a float? It’s as easy as
+`i.to_f`.
+              
+### Everything has a return value
+In Ruby you don’t require `return value`, or `result := value`, or
+`function_name = value`. Just `value`, alone, will return its value. Even `if`
+statements return values:
+
+~~~ ruby
+result = if answer == 'yes'
+            "The answer as affirmative."
+         else
+            "The answer was something else."
+         end
+~~~
+
+This example assigns the appropriate string to the variable `result`.
+
+
+Just enough Ruby
+----------------
+To work effectively with _Middlemac_ you’ll only have to learn enough Ruby to
+do a few simple things:
+
+- Set variables in the `config.rb` file.
+- Use a few helper functions from within files, e.g., `partial 'my_file'`.
+- Use conditionals, if you want them. You know: simply `if/else/end`, or even
+  `unless/else/end`.
+
+Examples of these last two points can be seen when we take a look at
+[File Types][filetypes_skill].

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/50_ruby_ecosystem.html.md.erb

@@ -0,0 +1,136 @@
+---
+title:  Ruby’s Ecosystem
+blurb:  Ruby has a huge ecosystem the can be confusing to new users. This
+        article makes a very brief introduction that should shorten the learning
+        curve.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Gems
+----
+
+“Gems” are packages of Ruby or compiled code in a standard format that serve as
+extensions or library additions to Ruby. _Middlemac_ is a system consisting of
+the `middlemac` gem, among others.
+
+By default Ruby is configured to fetch gems from
+[rubygems.org](https://rubygems.org/), which is convenient as long as you are
+connected to the internet.
+
+Gems, as software, have versions and can have dependencies on other gems. This
+can lead to dependency hell when multiple versions of multiple gems are
+installed having a clash due to mixed dependencies. Luckily this has been mostly
+solved via the use of Bundler.
+
+Bundler
+-------
+
+Bundler is a gem version management system that ensures that the correct gem
+version is used on a per-project basis, as specified in the `Gemfile` and locked
+in `Gemfile.lock` (more on these below).
+
+Using bundler will ensure that gem versions of known compatibility will be used.
+For example, _Middlemac_ requires _Middleman_ version 4.1.7 or higher, which
+itself requires other gems of specific versions. Bundler will ensure that when
+building a _Middlemac_ project, _only_ the correct gems are used.
+
+When you see a command such as:
+
+~~~ bash
+bundle exec middleman build
+~~~
+
+…it means that Bundler will execute the `middleman` gem, and will take
+responsibility for ensuring the correct gem versions are used. If we want to
+leave it up to chance, we might try this:
+
+~~~ bash
+middleman build
+~~~
+
+…and this might work, or it might not. Without using Bundler, the default
+versions of gems installed on your system will be used, and they might not be
+compatible the default version of `middleman`.
+
+Ruby projects, including _Middlemac_ help book projects, specify gem versions
+using a file in the project directory called `Gemfile`.
+
+
+`Gemfile` and `Gemfile.lock`
+----------------------------
+
+Your _Middlemac_ project contains this file to specify to Bundler which versions
+of Ruby gems should be used. In general you don't have to bother with this file
+at all. However if you become more advanced and want to use other gems, you’ll
+have to dive into this file eventually.
+
+This file contains gems and the versions that are allowed. For example,
+this documentation project’s `Gemfile` contains something similar to this:
+
+~~~ ruby
+gem 'middleman-pagegroups', '~> 1.0.3'
+~~~
+
+This declaration tells Bundler that `middleman-pagegroups` is a gem that is
+required for this project, and that any version greater than 1.0.3 is allowed,
+but only in the `1.0.x` series. The `~>` is called a “pessimistic operator” and
+is used if we don’t trust the `1.1.x` will break nothing.
+
+Other operators are available, too, of course, and are a simple web search away.
+
+The file `Gemfile.lock` is generated automatically by Bundler, and you should
+never, ever modify this file yourself (you should also exclude it from version
+control). This file is the file that indicates to Bundler the _exact_ versions
+of Gems that will be used. It ensures that the set of gems always stays
+consistent (even if you update gems) unless you deliberately want it to do
+otherwise.
+
+### `bundle install`
+
+When you `cd` into a project directory, you can:
+
+~~~ bash
+bundle install
+~~~
+
+This tells Bundler to check the `Gemfile` and install any gems that are required
+but are missing, typically from [rubygems.org](https://rubygems.org/). After
+installing the gems Bundler will also update the `Gemfile.lock`, thereby
+freezing the versions to be used in your project.
+
+What happens if I install a newer version of a Ruby gem? For example, if the
+`Gemfile` is configured to use `middleman-pagegroups` 1.0.3 or above, and I’ve
+been building with it for weeks, and then update my gem to 1.0.4? In this case,
+as long as 1.0.3 is still installed on your system, Bundler will still use this
+version.
+
+You’ll either have to update the `Gemfile` with 1.0.4 and then `bundle install`
+again, or…
+
+### `bundle update`
+
+This tells Bundler to install newer versions of all of your Gems, if available,
+and within the pessimistic version checks in the `Gemfile`, and also updates
+`Gemfile.lock` so that newer versions of the gems will be used.
+
+~~~ bash
+bundle update
+~~~
+
+
+`config.rb`
+-----------
+
+Nearly every Ruby project, including your _Middlemac_ help book project, follows
+the convention of configuration via a `config.rb` file in the root level of your
+project directory. 
+
+Information specific to _Middlemac_’s `config.rb` is available in the
+[appropriate section][setup-index] of this documentation.

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/60_filetypes_skill.html.md.erb

@@ -0,0 +1,165 @@
+---
+title:  File Types
+blurb:  <em>Middleman</em> uses several filetypes to get its job done. An
+        understanding of their differences is important to your successful use
+        of <em>Middlemac</em>.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Although you can use static `.html` files to build your help book, you would be
+sacrificing a lot of _Middleman_’s utility to do so, because static html is
+simply copied to your build directory as-is, with no opportunity to take
+advantages of the infrastructure that _Middleman_ and _Middlemac_ offer you.
+Instead you will probably chose a combination of `.haml`, `.md`, and `.erb`
+files, and even combinations of them in a single file!
+
+Filetype extensions
+-------------------
+As distributed, _Middleman_ (and thus _Middlemac_) understand several file type
+extensions and will process them accordingly.
+
+`.html`
+
+  : HTML files are regarded as already processed, and they will be copied
+    verbatim to the build directory.
+ 
+`.erb`
+
+  : Embedded Ruby files are files that contain Ruby code embedded in them. This
+    is useful for including simple if/else logic and including partials and
+    using helpers. Ruby code is delimited within `<%% %>` (generates no output)
+    or `<%%= %>` (does generate output) tags.
+    
+    For example, `<%%= "Hello, #{name}! %>` outputs a string into a generated
+    HTML document, and you will encounter several more examples within this
+    documentation.
+ 
+`.haml`
+
+  : The “HTML abstraction markup language” excels at enforcing structure in your
+    HTML-target documents, and is clutter-free and easy to read. It supports
+    many built-in filters for including content in Ruby, Markdown, raw source
+    code, and more. _Middlemac_’s templates, layouts, and partials are written
+    in HAML.
+    
+    You can learn more about HAML on [its website](http://haml.info/).
+
+`.md`
+
+  : Markdown is a plain-text formatting syntax that is exceedingly easy to read
+    and write in its source form, and mostly internally logically consistent.
+    _Middlemac_ uses [kramdown](http://kramdown.gettalong.org/) as its
+    text-to-HTML engine, and offers several useful features not found in
+    plain vanilla Markdown.
+     
+`.scss`
+
+  : “Sassy” CSS files use SASS markup and render into standard `.css` files.
+    You can use SASS as you see fit; it’s fully compatible with CSS, and all
+    CSS is valid SCSS. Why “SASS” and “SCSS”? SASS is the name of the project
+    as well as an older, non-CSS compatible format. So, SASS is the project,
+    and SCSS is the file format.
+    
+    You can learn more about SASS on [its website](http://sass-lang.com/).
+
+
+Files with a leading underscore
+-------------------------------
+
+Regardless of the file type, files with a leading underscore (“\_”) will be
+processed by _Middleman_ (if it’s a type that _Middleman_ recognizes), but
+_will not_ be copied to your build directory. An example of this type of file
+is a partial, which we want _Middleman_ to process and make ready for use, but
+which we don’t want copied to the output directory because its content will be
+included in other files that need it.
+
+
+Filetype chaining
+-----------------
+_This_ is what’s cool about the _Middleman_ build system: files are chained
+and processed multiple times by multiple processing systems, with the end
+result of producing the final file format. What does this mean? Let’s look at
+this example:
+
+`hello_world.html.erb`
+
+Middleman will produce a file (that’s then copied to the build output) named
+`hello_world.html` after processing it as an `.erb` file. For example:
+
+~~~~ erb
+<body>
+   <p><%%= hello_world_function %></p>
+</body>
+~~~~
+
+Will produce a `hello_world.html` file containing this (assuming that
+`hello_world_function` exists):
+
+~~~~ erb
+<body>
+   <p>Hello, world!</p>
+</body>
+~~~~
+
+What if we try this?
+
+`hello_world.html.md.erb`
+
+~~~~ markdown
+# Introduction
+<%%= hello_world_function %>
+~~~~
+
+Accounting for removing all of the HTML head section, etc., we end up with:
+
+~~~~ html
+<body>
+   <h1>Introduction</h1>
+   <p>Hello, world!</p>
+</body>
+~~~~
+
+It’s important to understand that file type chaining works from right to left.
+The last extension is processed first, then the penultimate extension, then the
+antepenultimate extension, etc.
+
+If you try to use a file named `hello_world.html.erb.md` then the results will
+be unexpected. Markdown will encounter `<%% %>` tag-sets and attempt to render
+them in HTML. When the ERB processor is passed the file, it will no longer
+encounter the tag-sets with the embedded Ruby.
+
+
+HAML rarely needs to be chained
+-------------------------------
+
+HAML includes filters and support for Ruby directly, and so it rarely needs to
+be chained. For example:
+
+~~~~ haml
+%h1 Introduction
+%p= hello_world_function
+- if true == true
+  %p Well, duh.
+%p
+  :markdown
+    _Today_a computer told me “Hello, world.” It was **only** addressing me,
+    and so I don’t know why it addressed me as the whole world.
+~~~~
+
+The use of `=` in the `%p=` tag is a flag that indicates HAML should be
+expecting Ruby code. Likewise, the solitary `-` indicates Ruby code and will not
+generate output. The use of `:markdown` indicates that Markdown-formatted text
+will be used.
+
+This might make you think that HAML is a Swiss Army knife, and why bother with
+other filetypes? Test it: once you’re familiar with the all of the basics,
+try coming back to this page’s source and convert if from `.html.md.erb` to
+`.html.haml`, and then choose whichever works for you.
+