middlemac 2.0.0 → 3.1.2

data/documentation_project/Contents/Resources/en.lproj/100_reference/010_apple_help_books/020_dissect_modern_help.html.md.erb

@@ -0,0 +1,246 @@
+---
+title:  Modern Apple Help Books
+blurb:  Apple doesn’t showcase it, but it provides the tools to build their
+        Help Books with every shipping version of macOS.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+Since macOS 10.10 (“Yosemite”), Apple has been using a JavaScript-based
+Help Book engine named “Eagle,” and has been gradually updating most of their
+application and macOS documentation to take advantage of it. You can find
+all of this engine located in `/Library/Documentation/Resources/Eagle/` on
+macOS 10.10 through macOS 10.13 (macOS 10.14 doesn’t seem to include it).
+
+This engine provides a common look, feel, and experience across all of Apple’s
+Help Books, and by taking advantage of Eagle, _Middlemac_ ensures that your
+own Help Books enjoy this same consistency.
+
+
+“Modern” Help
+-----------
+
+Modern Help Books are the Help Books you’ve seen on macOS Help, built-in
+application Help, and Apple software Help since macOS 10.10 was released. The
+term “modern” is only as valid as the term “next gen,” in that something newer
+always comes along.
+
+So it is with Apple, in that starting with macOS 10.13, some of the built in
+applications have been shipping with Help Books using their new “Harrier”
+Help Book development system. It’s likely that over time, shipping applications
+will be migrated toward this new look, too.
+
+_Middlemac_ will try to keep up with Apple Help technologies, and in the 
+meantime, version 3.0 produces Help Books meeting the same standards as current,
+shipping Apple Products.
+
+
+Modern Help Universal Deployment
+--------------------------------
+
+With Eagle, Apple has strived towards universal deployment of its Help Books,
+meaning that they are just as functional when served to a browser as they are
+when used in Apple Help Viewer. This also means that Apple strives to provide
+visual and functional consistency from Help Book to Help Book. This means that
+when served to a browser:
+
+- You have the same navigation menu that you would have in Apple Help Viewer.
+- You have the ability to search your Help Book within the browser environment,
+  just as you do within Apple Help Viewer.
+- The pages have the same appearance and behavior in the browser as they do in
+  Apple Help Viewer.
+- Certain features are automatic if the right conditions exist for them to
+  exist, such as Copyright Pages, navigation, Copyright Notices, and so on.
+- A single Help Book can provide its content in multiple languages, just as it
+  would in the browser.
+
+In short, an Eagle Help Book (or a Help Book produced by _Middlemac_) will work
+equally well when used in Apple Help Viewer as it does in a browser. And I mean
+the same Help Book; there’s no need to generate separate “Help Viewer” and
+“browser” versions.
+
+
+Eagle’s Heart
+-------------
+
+A modern Help Book is operated completely from a single HTML file within the
+Help Book. The `Resources/index.html` file uses JavaScript to load the content
+from your HTML files (in any localized directory) and presents them to the
+viewer. It also handles loading of all styles, operates special features such
+as tasks, performs searching, generates the navigation sidebar, and enables
+Copyright Pages, loads asides, and so on. 
+
+All of these functions fall into three broad categories:
+
+<% helpbook_task "help_modern_1", "Navigation" do %>
+
+“Navigation” encompasses things such a providing a nested menu structure for the
+Table of Contents, and enabling links to Copyright pages, if provided. The
+structure, depth, and relationships between Help Book pages which is required to
+provide this functionality is defined in the `navigation.json` file, which
+_Middlemac_ builds for you automatically based on your sitemap and the data that
+you provide in frontmatter.
+
+Using this Help Book’s `free` target `navigation.json` as an example (with much
+of the content stripped away for brevity), we can examine how Eagle constructs
+its navigation.
+
+| Key                                                | Sample Value (bold values static)   | Comments
+|----------------------------------------------------|-------------------------------------|----------
+| birdseed_version                                   | **5**                               | Probably an internal Apple framework version.
+| build_id                                           | "3.0.0"                             | Doesn’t affect Help Book.
+| build_date                                         | "2018.06.09-16:00:31"               | Doesn’t affect Help Book.
+| collect_feedback                                   | **false**                           | Probably refers to Apple’s "Was this page helpful?" feature. Unused by _Middlemac_.
+| copyright                                          | "topic-en.lproj/-acknowledgements"   | This is the `$topic_id` of the page to be used as the Copyright Page.
+| copyright_text                                     | "© 2018 Jim Derry."                 | Displayed on every page when viewed in browser, or when Help Viewer prints output.
+| css                                                | **""**                              | Unknown. Seems to have no effect on Help Book.
+| enable_tracking                                    | **false**                           | Probably an Apple tracking system. Unused by _Middlemac_.
+| framework                                          | "middlemac-3.0.0"                   | Probably an internal Apple framework reference.
+| icon                                               | "SharedGlobalArt/icon_32x32@2x.png" | Icon for the book. Unsure why this is different than the .plist’s HPDBookIconPath.
+| landing                                            | "topic-Resources-en.lproj/"          | This is the `$topic_id` of the page to be used as the Landing Page.
+| locale                                             | "en"                                | The locale of the JSON file.
+| platform                                           | **"mac"**                           | Probably because iTunes also supports Windows.
+| printable_page                                     | **""**                              | Unknown.
+| product                                            | "Middlemac"                         | Seems to be inactive.
+| quick_links                                        | **[]**                              | Unknown.
+| sections                                           | [Array]                             | Sections appear in the TOC with their given childen. Child order is important, but order of the sections in this array is not.
+| &nbsp;&nbsp;$section_id                            | "section-compose_project-helpers"   | Specify a $section_id for this section. Used to build the TOC.
+| &nbsp;&nbsp;&nbsp;&nbsp;name                       | "Helpers"                           | The name of the section as it will appear in the TOC.
+| &nbsp;&nbsp;&nbsp;&nbsp;children                   | [Array]                             | An array of `$topic_id` indicating the pages that constitute this section.
+| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$topic_id      | "topic-helpers-helpers"             | An element of the `$topic_id` list.
+| show_previous_next                                 | false                               | When set to true, enables previous and next page navigators.
+| source_schema                                      | **"apd-schema"**                    | Unknown.
+| title                                              | "Middlemac Help"                    | This will be used as the `<title>` of your landing page, reguardless of the `<title>` you set in the HTML document. Of course, it’s also used in the Help Viewer title bar and browser title banner.
+| toc                                                | [Array]                             | This array of `$topic_id` or `$section_id` defines the table of contents used in the sidebar.
+| &nbsp;&nbsp;$topic_id -or- $section_id             | "section-en.lproj/-reference"        | An element of the list.
+| topics                                             | [Array]                             | An array of `$topic_id`, as defined below.
+| &nbsp;&nbsp;$topic_id                              | "topic-asides-aside_description"    | Specify a `$topic_id` to represent a particular page.
+| &nbsp;&nbsp;&nbsp;&nbsp;name                       | "What is an aside?"                 | The name of the topic. Will be used in the TOC.
+| &nbsp;&nbsp;&nbsp;&nbsp;summary                    | "A short article describing…"       | The summary is shown in search results.
+| &nbsp;&nbsp;&nbsp;&nbsp;href                       | "asides/aside_description.html"     | The lproj-relative path of the file.
+| &nbsp;&nbsp;&nbsp;&nbsp;categories                 | [Array]                             | An array of `$category_name`; these will be applied as body classes when the document it loaded. Some categories have special purposes in Eagle, such a `aside` and `copyright`.
+| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$category_name | "aside"                             | An element of the list.
+| urls                                               | **{}**                              | Unknown.
+| version                                            | "3.0.0"                             | Probably the application version, but it’s not known where this is used in the Help Book.
+
+
+_Middlemac_ build this file for you automatically based on the `.lproj/` language,
+settings from your `config.rb` file, and page data including the overall site
+map as well as data from the pages’ frontmatter. If you feel like
+reverse-engineering Apple’s feedback and tracking mechanisms, then feel free
+to modify this file to your liking.
+
+
+<% end %>
+<% helpbook_task "help_modern_2", "Search" do %>
+
+When viewing a Help Book in Apple Help Viewer, the `.helpindex` file generated
+by `hiutil` is used. However this is a file produced by the old, deprecated
+`NSArchiver`, and is a binary format that JavaScript cannot parse or
+understand. Thus Eagle Help Books when viewed in the web browser refer to a
+different file in order to provide search results: `searchTree.json`.
+
+This file is a trie in JSON format, which is a very efficient structure for
+searching words.
+
+Apple _probably_ builds this file from the word frequency information gathered
+by `hiutil`, but because unarchiving the `.helpindex` requires the use of
+private Apple API’s, _Middlemac_ will generate this file from the contents of
+your pages itself. Thus there's the possibility that if Apple were to generate
+this file for you, there might be differences; however Apple is unlikely to
+perform this service for you.
+
+Words encountered as frontmatter `keywords` are given extra weight, and words
+encountered as frontmatter `exactmatch` are given a _lot_ of extra weight. The
+same list of stopwords (words ignored for searches) is used to build this file
+as to build the `.helpindex`.
+
+##### Search Redirects
+
+Both Apple’s `hiutil` and _Middlemac_’s `searchTree.json` indexer index
+individual pages. Search results link to those individual pages. However, recall
+that an Eagle Help Book never displays those pages directly; every page is
+loaded via JSON by the main `index.html` file, which is the only real “page”
+ever displayed.
+
+This means that when a page is listed as a search result, the link will
+attempt to deliver that specific page to you. That specific page is not
+`index.html`, and so there’s no loaded JavaScript or CSS. That’s not a good
+experience for users, and so _Middlemac_ addresses this issue by adding
+JavaScript to each of these individual pages which directs to the main
+`index.html`, including the correct URL query to load the desired page. By
+placing this redirect in the `<head>`, it’s usually fast enough to prevent
+loading the entire page into Apple Help Viewer, thus avoiding temporarily
+displaying unstyled pages.
+
+Apple’s JavaScript, of course, strips everything from the `<head>`, so when
+the file is ultimately AJAX-loaded into `index.html`, no circular refresh
+loops occur.
+
+
+<% end %>
+<% helpbook_task "help_modern_3", "Localization" do %>
+
+Eagle also provides localization features for browser-served pages that are
+handled automatically by Apple Help Viewer. For example, Apple Help Viewer
+knows that the OS is configured for Spanish, and will use the `Spanish.lproj/`
+or `es.lproj/` directory contents automatically. Apple Help Viewer will also
+fall back to `Base.lproj/` or `en.lproj/` if the localized directories are not
+part of the Help Book.
+
+Browsers, while they can provide the locale, aren’t nearly so smart about
+selecting paths properly, so Apple’s JavaScripts assume this role. The only
+caveat is that these JavaScripts don’t honor any type of `Base.lproj/`
+directory and `CFBundleDevelopmentRegion`. And because the browser is unable
+to select a proper `.lproj/` on its own, we have to provide some data that
+allows the JavaScript to select the proper folder.
+
+Additionally, because the locale determined by the browser is potentially not
+accurate for a variety of reasons, Apple’s JavaScripts present a language
+switcher on your Help Book’s landing page, if your project is multilingual.
+
+Thus, to make multilingual Help Books work in Apple Help Viewer, simply place a
+localized `.lproj/` for each language you support into the Help Book. To make
+multilingual Help Books work in the browser, though, we need to specify some
+additional metadata files: `Resources/locale-info.json` and
+`*.lproj/locale-list.json`.
+
+Of course, _Middlemac_ handles these two files for you, as long as you use the
+correct `.lproj/` directory name per
+`SharedGlobalAssets/_data/locale-list.json`, which is Apple’s standard locale
+list file. The [Directory Conventions][directory_conventions] topic shows which
+locales are supported out of the box.
+{: .tip .callout}
+
+Each `.lproj/` directory must contain a `locale-info.json`, which simply
+indicates some basic data about the locale present in that particular directory.
+
+More importantly, the site root must contain a `locale-list.json` which 
+indicates all of the locales in the present Help Book, and, importantly, which
+`.lproj/` directory the contents can be found.
+
+The `_data/locale-list.json` serves as a master list of all of the possible
+localizations. It may not be all inclusive, so feel free to add additional
+localizations if not already covered by this file. The 
+`Resources/locale-list.json`, generated by _Middlemac_, contains _only_ the
+locales used in the current project.
+{: .tip .callout}
+
+
+<% end %>
+
+
+## Middlemac and Eagle
+
+_Middlemac_ builds Eagle Help Books. Apple’s JavaScript has been modified
+slightly to provide support for non-flat file structures, and support for
+`<image>` tag `srcset` attributes.
+
+Some of Apple’s CSS has been overridden with more specificity to provide
+improvements to things such as `<dl>` that Apple doesn’t use often, but are
+critical for certain workflows.
+
+When you use _Middlemac_, you are building a real, true, Eagle Help Book, and
+not a copy, clone, or simulation.

data/documentation_project/Contents/Resources/en.lproj/100_reference/010_apple_help_books/index.html.md.erb

@@ -0,0 +1,4 @@
+---
+title:  Apple Help Books
+layout: layout-blank
+---

data/documentation_project/Contents/Resources/en.lproj/100_reference/030_backwards_compatibility.html.md.erb

@@ -0,0 +1,82 @@
+---
+title:  Backwards Compatibility
+blurb:  Notes about Backwards Compatibility with earlier versions of Middlemac.
+---
+<%= md_links %>
+<%= md_images %>
+
+_Middlemac_ version 3.0.0 is a **major** update. It’s an API-breaking update
+and projects using _Middlemac_ version 1._x_ or version 2._x_ will _not_ build
+without some changes to your project.
+
+This version of _Middlemac_ is a complete rewrite, and this was done in an
+effort to let Apple’s Help Book tools do their job and make modern Apple Help
+books. If you prefer full, manual control and custom styles that deviate from
+Apple’s look and feel, it’s suggested that you stick with _Middlemac_ version
+2.0.
+
+Middlemac 3.0 compared to older versions
+----------------------------------------
+
+_Middlemac_ versions prior to 3.0 were intended to provided tools giving you
+maximum control over page appearance while providing tools to allow automatic
+navigation within groups/sections. Although it shipped with layout templates
+and CSS to emulate the look of Apple’s Help Books for versions prior to
+macOS 10.10 (i.e., “Mavericks” and earlier), you were always encouraged to
+customize.
+
+_Middlemac_ 3.0, however, does away with _all of that_ in favor of building
+Apple Help Books that follow Apple’s own examples, standards, and practices.
+_Middlemac_ no longer builds Help Books that emulate a style, rather, Apple’s
+own tools provide the style and functionality. This necessarily represents a
+departure from the previous model of doing things.
+
+
+Project Upgrade Tips
+--------------------
+
+No automated method of upgrading a project is provided, but the steps for
+achieving an upgrade are fairly simple.
+
+The _vast_ majority of your source files will continue to work as they did in
+the past, although you may wish to reorganize them to align nicely with the way
+that modern Apple Help Books work. Here are some tips to help you migrate
+faster:
+
+- Begin by _reading_ this documentation and having a close look at the sample
+  project.
+
+- Take a look at the [Directory and File Reference][directory_reference],
+  to have a good understanding of what all of the new files do, and what their
+  functions are.
+
+- **It’s probably easiest to move your old source HTML files into the new sample
+  project.**
+
+- Some Markdown reference style links may have their references changed. Keep a
+  lookout for this.
+
+- There’s a new option called `show_debug` in the new `config.rb` file. Set this
+  to `true` to see all of the `md_links` and `md_images` values at the bottom
+  of each Help Book page. This setting will also highlight non-working Markdown
+  reference style links.
+
+- `Base.lproj` is not supported by modern Apple Help Books. Ensure that this
+  directory is named `en.lproj`, or some other locale name supported by Apple’s
+  Help Book system.
+  
+- Group landing pages are no longer supported, because modern Apple Help Books
+  do no use them. Instead, group landing pages are now used solely as metadata
+  containers to provide the name of the group. If you absolutely require a
+  landing page, you can create a topic page in the group.
+  
+- In Apple parlance, “groups” are now called “sections,” although in order to
+  preserve as much backwards compatibility as possible, functions relating to
+  groups, if you use them, refer to groups.
+
+- Most of the group navigation features and all of the helpers are no longer
+  included, nor are breadcrumbs. Modern Apple Help Books do not use them, and
+  handle all navigation via their JavaScript, so this support was dropped. If
+  you wish to go against Apple’s style, you can re-introduce these partials from
+  an older version of _Middleman_ yourself, as all of the internal logic is
+  still present.

data/documentation_project/Contents/Resources/en.lproj/100_reference/040_directory_reference.html.md.erb

@@ -0,0 +1,276 @@
+---
+title:  Directory and File Reference
+blurb:  Let us examine all of the files and folders in a standard
+        <em>Middlemac</em> project folder.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+
+`your_project/`
+
+: This is the self-contained directory containing everything that you need to
+  configure and build your project.
+  
+`your_project/config.rb`
+
+: This file contains most of your project settings for configuring
+  _Middlemac_, _Middleman_, and other _Middleman_ extensions you might add
+  in the future. 
+
+`your_project/Gemfile`
+
+: This file keeps track of the Ruby dependencies that are required for
+  _Middleman_ to work. You can edit this file to add additional _Middleman_
+  extensions, should you wish _Middlemac_/_Middleman_ do something more.
+
+`your_project/Gemfile.lock`
+
+: This is the bundler-generated file specifying the _exact_ dependency
+  configuration used. As Ruby Gems are updated on your system, this file will
+  ensure that updated versions are _not_ used, so that your configuration
+  stays frozen and steady. You can `bundle update` when you are ready to use
+  the newest version of Gems; doing so regenerates this file.
+
+`your_project/middlemac.webloc`
+
+: This is a convenient shortcut that, when used, will open your Help Book
+  in the default browser to the main `index.html` file.
+
+`your_project/Contents/`
+
+: Contains everything in your help project that will be compiled into or
+  contribute to the final `.help` project.
+   
+
+`your_project/Contents/Info.plist.erb`
+
+: The `Info.plist.erb` file is the file that _Middlemac_ will process into the
+  final `Info.plist` that your macOS application needs in order to work with
+  your Help Book. For a basic project you shouldn’t have to modify anything in
+  this file, but if you want or need to have other key-value pairs in the
+  final `Info.plist`, then add them here. 
+   
+
+`your_project/Contents/Resources/index.html`
+
+: This file is the heart of your entire modern Help Book. When the Help Book
+  is open in Apple Help Viewer or being served to your web browser, it is the
+  only page that you will ever truly see. The entire rest of your Help Book,
+  in any language, is loaded by this file for display via AJAX. Consequently,
+  it strips out most of the `<head>` information from your own files, loads
+  all of the JavaScripts and styles, and manages language selection, TOC, and
+  everything else in your Help Book.
+  
+  The data that appear in your generated HTML documents’ `<head>` is still
+  critical to the Apple Help Indexer. Don’t try to simplify things by removing
+  these items from the layout templates.
+  
+  You generally should never have to edit this file, unless you want to
+  include some CSS or JavaScript that is not provided by _Middlemac_.
+
+
+`your_project/Contents/Resources/locale-list.json.erb`
+
+: When served to a web browser, Apple’s JavaScript will refer to this file
+  to determine which languages are available. This file is managed
+  automatically by _Middlemac_ based on the actual `language.lproj` files
+  that are present in your project.
+   
+   
+`your_project/Contents/Resources/SharedGlobalAssets/`
+
+: This directory contains assets that are common between all of your 
+  different help language projects, as well as assets that _Middlemac_
+  requires by convention, such as Apple’s CSS and JavaScripts, certain image
+  files, data files, layouts, and so on.
+   
+   
+`your_project/Contents/Resources/SharedGlobalAssets/_data/`
+
+: This directory contains data files that you can use to supply data for
+  [using local data][local_data]. This directory will not be
+  output in the final build.
+    
+
+`your_project/Contents/Resources/SharedGlobalAssets/_data/locale-list.json`
+
+: This file contains all of the source information for the locales that
+  _Middlemac_ supports “out of the box,” and is the same that Apple
+  generally provides for most of its applications. You should consult this
+  file to determine the correct `language.lproj` directory name to use for
+  developing help for locales other then the default `en.lproj`.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/`
+
+: All layouts and templates should go here. This directory will not be
+  output in the final build.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-apple-modern-aside.haml`
+
+: This is the layout use for “aside” files. Your asides should set their
+  `layout` frontmatter key to this layout.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-apple-modern.haml`
+
+: This is the layout for all content files, and is used by default when
+  the frontmatter does not override it with a different `layout` key.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-blank.haml`
+
+: This is a layout that generates no content, and should be used for group
+  metadata `index.html` files.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-hpd.haml`
+
+: This is a layout used by `index_hpd.html` files at the root level of each of
+  your languages, and simply causes a redirect to the proper `index.html` file
+  in that directory. 
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_partials/`
+
+: Partials can go here, and should be prefaced with an underscore so that
+  they will not generate build output. Partial files can also be included
+  in any other directory, too. This is for organizational convenience of
+  common partials that may be used anywhere.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/convention/`
+
+: Images that the Apple Help Book and _Middlemac_ require by convention go
+  here. This is separate from the `images/` directory simply to make
+  directory management simpler by avoiding the mixing of required and
+  non-required files.
+  
+  
+`your_project/Contents/Resources/SharedGlobalAssets/css/`
+
+: Your `.css` and `.scss` files should go here.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/css/apple/`
+
+: Apple’s CSS and CSS related files exist in this directory.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/css/middlemac/`
+
+: _Middlemac_’s CSS and CSS related files exist in this directory.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/fonts/`
+
+: Any fonts that you wish to include should go here. In general if you are
+  building an Apple Help Book, additional fonts should not be needed.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/images/`
+
+: All images should go here. _Middleman_ will find them automatically if
+  you use the helpers.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/js/`
+
+: Javascripts, if any, should go here. They will not be included
+  automatically in your project unless you modify the main `index.html`
+  file to include them.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/js/app.5.1.xx.js`
+`your_project/Contents/Resources/SharedGlobalAssets/js/middlemac-debug.js`
+`your_project/Contents/Resources/SharedGlobalAssets/js/vendor.js`
+
+: These are the Apple and _Middlemac_ JavaScript files that operate the
+  modern Apple Help Book. Note that the `app.5.1.xx.js` file is as Apple
+  originally provides it, with some minor editing to work with `<img>` tag
+  `srcset` attributes.
+  
+  You should add any JavaScripts that your HelpBook requires here, and then
+  modify the main `index.html` file to include them.
+
+   
+`your_project/Contents/Resources/en.lproj`
+
+: This directory serves as your base [group][groups] for the English version
+  of your Help Book, and it contains all of your Help Book’s content,
+  including locale-specific versions of your resources.
+   
+  Any other files that result in `.html` in this directory level, except for
+  `index.html` constitute part of the `en.lproj` group. At this level you
+  should start adding directories to contain your other groups.
+   
+  Certainly, you’re not required to develop in English, and _Middlemac_
+  supports multiple languages simultaneously. Out of the box, you can use
+  any language supported by `SharedGlobalAssets/_data/locale-list.json`.
+
+`your_project/Contents/Resources/en.lproj/ExactMatch.plist.erb`
+
+: This file supplements the `.helpindex` file when the Help Book is viewed in
+  Apple Help Viewer by providing exact word matching. _Middlemac_ generates
+  the finished version of this file based on the `exactmatch` keys in your
+  pages’ frontmatter. See [Apple’s documentation][1] for details.
+
+   
+`your_project/Contents/Resources/en.lproj/index_hpd.html.md.erb`
+
+: This is the file pointed to by the `Info.plist` key `HPDBookAccessPath`,
+  and simply redirects to the language’s actual `index.html` file in the built
+  project. This is required to avoid conflicts with recent versions of macOS
+  wherein **Help Viewer** gets confused when there are multiple `index.html`
+  files in both the language level and the `/Resources` directory.
+
+
+`your_project/Contents/Resources/en.lproj/InfoPlist.strings`
+
+: The `InfoPlist.strings` file is the file that _Middlemac_ will process into
+ the final `InfoPlist.strings`, which contains the localized version of your
+ applications’ human-readable `Info.plist` data (specifically, `CFBundleName`
+ and `HPDBookTitle`).
+
+
+`your_project/Contents/Resources/en.lproj/locale-info.json.erb`
+
+: This file contains metadata used by Apple’s JavaScript to understand the
+  locale details for this locale’s directory. It is managed automatically by
+  _Middlemac_.  
+
+
+`your_project/Contents/Resources/en.lproj/navigation.json.erb`
+
+: _Middlemac_ builds the output version of this file from your Help Book’s
+  sitemap. It is used by Apple’s JavaScript to make all of the navigation
+  features possible.
+
+
+`your_project/Contents/Resources/en.lproj/searchTree.json..erb`
+
+: This file contains the search index used when your Help Book is viewed in
+  a browser. _Middlemac_ generates the final version of this file when it
+  indexes your Help Book.
+
+
+`your_project/Contents/Resources/en.lproj/asides/`
+
+: This optional folder can be used to hold your aside files. Besides being a
+  convenient organizational location, it has the magic property of not
+  requiring the `aside` category in their frontmatter.
+
+`your_project/Contents/Resources/en.lproj/assets/`
+
+: This directory contains all of the localized assets used in your Help Book.
+ In order for _Middlemac_’s asset helpers such as `image_tag` and `partial`
+ to find localized resources, any subdirectories of `assets/` must mirror
+ the subdirectories of `SharedGlobalAssets/`, e.g., `assets/images/`.  
+{: .nontabular}
+
+
+ [1]: https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW5