markdown_helper 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bd8b799693304f32aad8780f7d4ce734ae46614d
-  data.tar.gz: 703df7ba48954272c6bfe0e794b9150564f4d3cd
+SHA256:
+  metadata.gz: cee806406f109c72b11a7a4f78c8ad7efc59706f278a0a5b654267e3ae38ddf6
+  data.tar.gz: 4e49e14011eb429bd5d523a314572aff3693876b07fa50b52d9cfecf693fcd3d
 SHA512:
-  metadata.gz: efc921a959dd8f3c0cd39d0da08e13dcb6c51f7b82ab405d37e1faf6f4ff81218ae6264e8963e8aa8de67ebad4521145e9bd044c5b7eb4ced8e9003a6461919a
-  data.tar.gz: a91f66a74094c2bab6e87bbf98403ed168df5d817a4155f7440b9c7cca8c181171c02bea25d6fc6b882794bc617519f127e3a0da15b576ea3cb6e411bada3194
+  metadata.gz: 5d4c4a25171b3ac8df8cfd84766843ae7c8d599c896d70b1d70854353dc7f0cb06741d1832640f5f24fdc500285bf16684f09d7d08450a48c73680d0033cab9f
+  data.tar.gz: 5f81f39ad84273fa2367a03e7bc18773190c97398ff7ac3c8834eac464a2a9dbe8bbedbf566fee79489124d2458fc32bfec96534b85f2edd4a7cadbb1e5dd63c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_helper (2.0.0)
+    markdown_helper (2.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,38 +1,58 @@
 <!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE README.template.md -->
 # Markdown Helper
 
-![Gem Version](https://badge.fury.io/rb/markdown_helper.svg) [Visit gem markdown_helper](https://rubygems.org/gems/markdown_helper)
-
-## Deprecated
-
-- Method ```:resolve```.
-- Command ```markdown_helper resolve```.
+[![Gem](https://img.shields.io/gem/v/markdown_helper.svg?style=flat)](http://rubygems.org/gems/markdown_helper "View this project in Rubygems")
 
 ## What's New?
 
-Treatments for included file:
-
-- Support is added for including a file as a comment.  See the [use case](markdown/use_cases/include_files/include_text_as_comment/use_case.md#include-text-as-comment).
-- Support is added for including a file as pre-formatted.  See the [use case](markdown/use_cases/include_files/include_text_as_pre/use_case.md#include-text-as-pre).
-
-(The new version, 2.0.0, is not a major increment over version 1.9.9.  Numbers just ran out.)
+Page TOC (table of contents) is improved:
+
+- **Old**:  You would first run the markdown helper to generate a page TOC, then run the helper a second time to include the page TOC where you want it.
+- **New**:  You specify the site for the page TOC in the page itself, and the page TOC is automatically generated and inserted there.  See the [use case](markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc)
+
+The old way is now deprecated.
+
+## Contents
+- [What's a Markdown Helper?](#whats-a-markdown-helper)
+- [How It Works](#how-it-works)
+  - [Restriction: ```git``` Only](#restriction-git-only)
+  - [Commented or Pristine?](#commented-or-pristine)
+- [File Inclusion](#file-inclusion)
+  - [Re-use Text](#re-use-text)
+  - [Include Generated Text](#include-generated-text)
+  - [Nest Inclusions](#nest-inclusions)
+  - [Merged Text Formats](#merged-text-formats)
+    - [Markdown](#markdown)
+    - [Highlighted Code Block](#highlighted-code-block)
+    - [Plain Code Block](#plain-code-block)
+    - [Comment](#comment)
+  - [Pre-Formattted Text](#pre-formattted-text)
+  - [Usage](#usage)
+    - [CLI](#cli)
+    - [API](#api)
+    - [Include Descriptions](#include-descriptions)
+      - [Example Include Descriptions](#example-include-descriptions)
+    - [Page TOC](#page-toc)
+    - [Diagnostics](#diagnostics)
+      - ["Noisy" (Not Pristine)](#noisy-not-pristine)
+      - [Missing Includee File](#missing-includee-file)
+      - [Circular Inclusion](#circular-inclusion)
+- [What Should Be Next?](#what-should-be-next)
 
 ## What's a Markdown Helper?
 
 Class <code>MarkdownHelper</code> supports:
 
 * [File inclusion](#file-inclusion): to include text from other files, as code-block or markdown.
-* [Page TOC](#page-toc): to create the table of contents for a markdown page.
-* [Image path resolution](#image-path-resolution): to resolve relative image paths to absolute URL paths (so they work even in gem documentation). [Deprecated]**
-* [Image attributes](#image-attributes): image attributes are passed through to an HTML <code>img</code> tag.  [Deprecated]**
+* [Page TOC](#page-toc): to create and insert the table of contents for a markdown page.
 
 ## How It Works
 
 The markdown helper is a preprocessor that reads a markdown document (template) and writes another markdown document.
 
-The template can contain certain instructions that call for file inclusions and image resolutions.
+The template can contain certain instructions that call for file inclusions.
 
-### Restriction:  ```git``` Only
+### Restriction: ```git``` Only
 
 The helper works only in a ```git``` project:  the working directory or one of ita parents must be a git directory -- one in which command ```git rev-parse --git-dir``` succeeds.
 
@@ -42,11 +62,10 @@ By default, the output markdown has added comments that show:
 
 * The path to the template file.
 * The path to each included file.
-* The image description (original) for each resolved image file path.  [Deprecated]**
 
 You can suppress those comments using the <code>pristine</code> option.
 
-## File Inclusion 
+## File Inclusion
 
 <img src="images/include.png" alt="include_icon" width="50">
 
@@ -54,49 +73,41 @@ This markdown helper enables file inclusion in GitHub markdown.
 
 (Actually, this README file itself is built using file inclusion.)
 
-Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
+See all [use cases](markdown/use_cases/use_cases.md#use-cases).
+
+### Re-use Text
+
+Keep your markdown DRY (Don't Repeat Yourself) by re-using text.  See the [use case](markdown/use_cases/include_files/reuse_text/use_case.md#reuse-text).
+
+### Include Generated Text
+
+In particular, you can include text that's built during your "readme build."  See the [use case](markdown/use_cases/include_files/include_generated_text/use_case.md#include-generated-text).
 
-See the [use cases](markdown/use_cases/use_cases.md#use-cases).
+### Nest Inclusions
+
+You can nest inclusions.  See the [use case](markdown/use_cases/include_files/nest_inclusions/use_case.md#nest-inclusions).
 
 ### Merged Text Formats
 
+#### Markdown
+
+You can include text that is to be treated simply as markdown.  See the [use case](markdown/use_cases/include_files/include_markdown/use_case.md#include-markdown).
+
 #### Highlighted Code Block
 
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/readme/include.rb -->
-```include.rb```:
-```ruby
-class RubyCode
-  def initialize
-    raise RuntimeError.new('I am only an example!')
-  end
-end
-```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/readme/include.rb -->
+You can include a code block that's to be highlighted.  See the [use case](markdown/use_cases/include_files/include_highlighted_code/use_case.md#include-highlighted-code).
 
 #### Plain Code Block
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/readme/include.rb -->
-```include.rb```:
-```
-class RubyCode
-  def initialize
-    raise RuntimeError.new('I am only an example!')
-  end
-end
-```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/readme/include.rb -->
-
-[Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
+You can also include a code block without highlighting.  See the [use case](markdown/use_cases/include_files/include_code_block/use_case.md#include-code-block).
 
 #### Comment
 
-Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
-
-#### Markdown
+You can include text that's to become a comment in the markdown.  See the [use case](markdown/use_cases/include_files/include_text_as_comment/use_case.md#include-text-as-comment).
 
-Markdown text is included unadorned, and will be processed on GitHub as markdown.
+### Pre-Formattted Text
 
-The markdown text is itself scanned for nested includes.
+You can include text that's pre-formatted.  See the [use case](markdown/use_cases/include_files/include_text_as_pre/use_case.md#include-text-as-pre).
 
 ### Usage
 
@@ -131,9 +142,8 @@ require 'markdown_helper'
 
 template_file_path = 'highlight_ruby_template.md'
 markdown_file_path = 'highlighted_ruby.md'
-markdown_helper = MarkdownHelper.new
-markdown_helper.include(template_file_path, markdown_file_path)
 # Pristine.
+markdown_helper = MarkdownHelper.new
 markdown_helper.pristine = true
 markdown_helper.include(template_file_path, markdown_file_path)
 # Also pristine.
@@ -154,6 +164,8 @@ where:
   * Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
   * <code>[:code_block]</code>, to include a plain code block.
   * <code>[:markdown]</code>, to include text markdown (to be rendered as markdown).
+  * <code>[:comment]</code>, to insert text as a markdown comment.
+  * <code>[:pre]</code>, to include pre-formatted text.
 * *relative_file_path* points to the file to be included.
 
 ##### Example Include Descriptions
@@ -166,176 +178,30 @@ where:
 @[:code_block](my_language.xyzzy)
 
 @[:markdown](my_markdown.md)
-```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/readme/include.md -->
-
-## Page TOC
-
-The markdown helper can create the table of contents for a markdown page.
-- The TOC is a tree of links to the headers on the page, suitable for inclusion with the page itself.
-- See the [use case](markdown/use_cases/tables_of_contents/create_and_include_page_toc/use_case.md#create-and-include-page-toc).
-
-
-
-## Image Path Resolution **[Deprecated]**
-
-<img src="images/image.png" alt="image_icon" width="50">
-
-This markdown helper enables image path resolution in GitHub markdown.
-
-(Actually, this README file itself is built using image path resolution.)
-
-Use the markdown helper to resolve image relative paths in a markdown (</code>.md</code>) file.
-
-This matters because when markdown becomes part of a Ruby gem, its images will have been relocated in the documentation at RubyDoc.info, breaking the relative paths. The resolved (absolute) urls, however, will still be valid.
-
-### Usage
-
-#### CLI
-
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE bin/usage/resolve.txt -->
-```resolve.txt```:
-```
-
-Usage: markdown_helper resolve [options] template_file_path markdown_file_path
-        --pristine                   No comments added
-        --help                       Display help
-    
-  where
-
-    * template_file_path is the path to an existing file.
-    * markdown_file_path is the path to a file to be created.
-
-  Typically:
-
-    * Both file types are .md.
-    * The template file contains image descriptions.
-```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE bin/usage/resolve.txt -->
-
-#### API
-
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/readme/resolve_usage.rb -->
-```resolve_usage.rb```:
-```ruby
-require 'markdown_helper'
 
-template_file_path = 'template.md'
-markdown_file_path = 'markdown.md'
-markdown_helper = MarkdownHelper.new
-markdown_helper.resolve(template_file_path, markdown_file_path)
-# Pristine.
-markdown_helper.pristine = true
-markdown_helper.resolve(template_file_path, markdown_file_path)
-# Also pristine.
-markdown_helper = MarkdownHelper.new(:pristine => true)
-markdown_helper.resolve(template_file_path, markdown_file_path)
-```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/readme/resolve_usage.rb -->
-
-#### Image Descriptions
-
-Specify each image  at the beginning of a line via an *image description*, which has the form:
-
-<code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
-
-where:
-
-* *alt_text* is the usual alt text for an HTML image.
-* *relative_file_path* points to the file to be included.
-* *attributes* specify image attributes.  See [Image Attributes](#image-attributes) below.
-
-##### Example Image Descriptions
-
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/readme/resolve.md -->
-```resolve.md```:
-```code_block
-![my_alt](image/image.png)
-
-![my_alt](image/image.png | width=50)
-
-![my_alt](image/image.png| width=50 height=50)
-```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/readme/resolve.md -->
-
-## Image Attributes
-
-<img src="images/html.png" alt="html_icon" width="50">
-
-This markdown helper enables HTML image attributes in GitHub markdown [image descriptions](https://github.github.com/gfm/#image-description).
-
-(Actually, this README file itself is built using image attributes.)
-
-Use the markdown helper to add image attributes in a markdown (</code>.md</code>) file.
-
-### Usage
-
-#### CLI
-
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE bin/usage/resolve.txt -->
-```resolve.txt```:
-```
-
-Usage: markdown_helper resolve [options] template_file_path markdown_file_path
-        --pristine                   No comments added
-        --help                       Display help
-    
-  where
+@[:comment](my_comment.txt)
 
-    * template_file_path is the path to an existing file.
-    * markdown_file_path is the path to a file to be created.
-
-  Typically:
-
-    * Both file types are .md.
-    * The template file contains image descriptions.
+@[:pre](my_preformatted.txt)
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE bin/usage/resolve.txt -->
-
-#### API
-
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/readme/resolve_usage.rb -->
-```resolve_usage.rb```:
-```ruby
-require 'markdown_helper'
-
-template_file_path = 'template.md'
-markdown_file_path = 'markdown.md'
-markdown_helper = MarkdownHelper.new
-markdown_helper.resolve(template_file_path, markdown_file_path)
-# Pristine.
-markdown_helper.pristine = true
-markdown_helper.resolve(template_file_path, markdown_file_path)
-# Also pristine.
-markdown_helper = MarkdownHelper.new(:pristine => true)
-markdown_helper.resolve(template_file_path, markdown_file_path)
-```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/readme/resolve_usage.rb -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/readme/include.md -->
 
-#### Image Descriptions
+#### Page TOC
 
-Specify each image at the beginning of a line  via an *image description*, which has the form:
+You can specify the location for an automatically-generated page TOC (table of cotents).  See the [use case](markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc).
 
-<code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
+#### Diagnostics
 
-where:
+##### "Noisy" (Not Pristine)
 
-* *alt_text* is the usual alt text for an HTML image.
-* *relative_file_path* points to the file to be included.
-* *attributes* are whitespace-separated name-value pairs in the form *name*<code>=</code>*value*.  These are passed through to the generated <code>img</code> HTML element.
+By default, the markdown helper inserts comments indicating inclusions.  See the [use case](markdown/use_cases/include_files/include_with_added_comments/use_case.md#include-with-added-comments).
 
-##### Example Image Descriptions
+##### Missing Includee File
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/readme/resolve.md -->
-```resolve.md```:
-```code_block
-![my_alt](image/image.png)
+A missing includee file causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include_files/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
 
-![my_alt](image/image.png | width=50)
+##### Circular Inclusion
 
-![my_alt](image/image.png| width=50 height=50)
-```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/readme/resolve.md -->
+A circular inclusion causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include_files/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
 
 ## What Should Be Next?
 

data/Rakefile

@@ -28,7 +28,6 @@ namespace :build do
     %w/
         create_page_toc
         include
-        resolve
     /.each do |executable_name|
       usage_text = `ruby bin/_#{executable_name} --help`
       usage_file_path = "bin/usage/#{executable_name}.txt"

data/lib/markdown_helper.rb

@@ -1,10 +1,6 @@
 require 'pathname'
 require 'markdown_helper/version'
 
-# Helper class for working with GitHub markdown.
-#  Supports file inclusion.
-#
-# @author Burdette Lamar
 class MarkdownHelper
 
   class MarkdownHelperError < RuntimeError; end
@@ -13,14 +9,19 @@ class MarkdownHelper
   class TocHeadingsError < MarkdownHelperError; end
   class OptionError < MarkdownHelperError; end
   class EnvironmentError < MarkdownHelperError; end
+  class InvalidTocTitleError < MarkdownHelperError; end
+  class MisplacedPageTocError < MarkdownHelperError; end
+  class MultiplePageTocError < MarkdownHelperError; end
 
-  IMAGE_REGEXP = /!\[([^\[]+)\]\(([^)]+)\)/
   INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)$/
 
   attr_accessor :pristine
 
   def initialize(options = {})
     # Confirm that we're in a git project.
+    # This is necessary so that we can prune file paths in the tests,
+    # which otherwise would fail because of differing installation directories.
+    # It also allows pruned paths to be used in the inserted comments (when not pristine).
     MarkdownHelper.git_clone_dir_path
     default_options = {
         :pristine => false,
@@ -36,19 +37,6 @@ class MarkdownHelper
     end
   end
 
-  # Merges external files into markdown text.
-  # @param template_file_path [String] the path to the input template markdown file, usually containing include pragmas.
-  # @param markdown_file_path [String] the path to the output merged markdown file.
-  # @return [String] the resulting markdown text.
-  #
-  # @example pragma to include text as a highlighted code block.
-  #   @[ruby](foo.rb)
-  #
-  # @example pragma to include text as a plain code block.
-  #   @[:code_block](foo.xyz)
-  #
-  # @example pragma to include text markdown, to be rendered as markdown.
-  #   @[:markdown](foo.md)
   def include(template_file_path, markdown_file_path)
     send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
       send(:include_files, template_file_path, input_lines, output_lines, Inclusions.new)
@@ -56,41 +44,17 @@ class MarkdownHelper
   end
 
   def create_page_toc(markdown_file_path, toc_file_path)
+    message = <<EOT
+Method create_page_toc is deprecated.
+Please use method include with embedded :page_toc treatment.
+See https://github.com/BurdetteLamar/markdown_helper/blob/master/markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc.
+EOT
+    warn(message)
     send(:generate_file, markdown_file_path, toc_file_path, __method__) do |input_lines, output_lines|
       send(:_create_page_toc, input_lines, output_lines)
     end
   end
 
-  # Resolves relative image paths to absolute urls in markdown text.
-  # @param template_file_path [String] the path to the input template markdown file, usually containing image pragmas.
-  # @param markdown_file_path [String] the path to the output resolved markdown file.
-  # @return [String] the resulting markdown text.
-  #
-  # This matters because when markdown becomes part of a Ruby gem,
-  # its images will have been relocated in the documentation at RubyDoc.info, breaking the paths.
-  # The resolved (absolute) urls, however, will still be valid.
-  #
-  # ENV['REPO_USER'] and ENV['REPO_NAME'] must give the user name and repository name of the relevant GitHub repository.
-  #  must give the repo name of the relevant GitHub repository.
-  #
-  # @example pragma for an image:
-  #   ![image_icon](images/image.png)
-  #
-  # The path resolves to:
-  #
-  #   image_path = File.join(
-  #       "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
-  #       relative_file_path,
-  #   )
-  def resolve(template_file_path, markdown_file_path)
-    # Method :generate_file does the first things, yields the block, does the last things.
-    warn("Method :resolve is deprecated")
-    send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
-      send(:resolve_images, template_file_path, input_lines, output_lines)
-    end
-  end
-  alias resolve_image_urls resolve
-
   private
 
   class Heading
@@ -115,8 +79,14 @@ class MarkdownHelper
       self.new(level, title)
     end
 
+
     def link
-      anchor = title.gsub(/\W+/, '-').downcase
+      remove_regexp = /[\#\(\)\[\]\{\}\.\?\+\*\`\"\']+/
+      to_hyphen_regexp = /\W+/
+      anchor = title.
+          gsub(remove_regexp, '').
+          gsub(to_hyphen_regexp, '-').
+          downcase
       "[#{title}](##{anchor})"
     end
 
@@ -126,16 +96,6 @@ class MarkdownHelper
     "<!--#{text}-->\n"
   end
 
-  def repo_user_and_name
-    repo_user = ENV['REPO_USER']
-    repo_name = ENV['REPO_NAME']
-    unless repo_user and repo_name
-      message = 'ENV values for both REPO_USER and REPO_NAME must be defined.'
-      raise EnvironmentError.new(message)
-    end
-    [repo_user, repo_name]
-  end
-
   def generate_file(template_file_path, markdown_file_path, method)
     unless File.readable?(template_file_path)
       message = [
@@ -152,44 +112,104 @@ class MarkdownHelper
       yield input_lines, output_lines
       output_lines.push(MarkdownHelper.comment(" <<<<<< END GENERATED FILE (#{method.to_s}): SOURCE #{template_path_in_project} ")) unless pristine
     end
-    output = output_lines.join('')
-    File.write(markdown_file_path, output)
-    output
+    File.open(markdown_file_path, 'w') do |file|
+      output_lines.each do |line|
+        file.write(line)
+      end
+    end
   end
 
   def _create_page_toc(input_lines, output_lines)
-    level_one_seen = false
+    first_heading_level = nil
     input_lines.each do |input_line|
-      input_line.chomp!
-      heading = Heading.parse(input_line)
+      line = input_line.chomp
+      heading = Heading.parse(line)
       next unless heading
-      unless level_one_seen || heading.level == 1
-        message = "First heading must be level 1, not '#{input_line}'"
-        raise TocHeadingsError.new(message)
-      end
-      level_one_seen = true
-      indentation = '  ' * heading.level
+      first_heading_level ||= heading.level
+      indentation = '  ' * (heading.level - first_heading_level)
       output_line = "#{indentation}- #{heading.link}"
       output_lines.push("#{output_line}\n")
     end
   end
 
   def include_files(includer_file_path, input_lines, output_lines, inclusions)
-
+    markdown_lines = []
+    page_toc_inclusion = nil
     input_lines.each_with_index do |input_line, line_index|
       match_data = input_line.match(INCLUDE_REGEXP)
       unless match_data
-        output_lines.push(input_line)
+        markdown_lines.push(input_line)
         next
       end
       treatment = match_data[1]
       cited_includee_file_path = match_data[2]
-      inclusions.include(
+      new_inclusion = Inclusion.new(
           input_line.chomp,
           includer_file_path,
           line_index + 1,
           cited_includee_file_path,
-          treatment,
+          treatment
+      )
+      case treatment
+      when ':markdown'
+        inclusions.include(
+            new_inclusion,
+            markdown_lines,
+            self
+        )
+      when ':page_toc'
+        unless inclusions.inclusions.size == 0
+          message = 'Page TOC must be in outermost markdown file.'
+          raise MisplacedPageTocError.new(message)
+        end
+        unless page_toc_inclusion.nil?
+          message = 'Only one page TOC allowed.'
+          raise MultiplePageTocError.new(message)
+        end
+        page_toc_inclusion = new_inclusion
+        toc_title = match_data[2]
+        title_regexp = /^\#{1,6}\s/
+        unless toc_title.match(title_regexp)
+          message = "TOC title must be a valid markdown header, not #{toc_title}"
+          raise InvalidTocTitleError.new(message)
+        end
+        page_toc_inclusion.page_toc_title = toc_title
+        page_toc_inclusion.page_toc_line = input_line
+        markdown_lines.push(input_line)
+      else
+        markdown_lines.push(input_line)
+      end
+    end
+    # If needed, create page TOC and insert into markdown_lines.
+    unless page_toc_inclusion.nil?
+      toc_lines = [
+          page_toc_inclusion.page_toc_title + "\n",
+          '',
+      ]
+      page_toc_index =  markdown_lines.index(page_toc_inclusion.page_toc_line)
+      lines_to_scan = markdown_lines[page_toc_index + 1..-1]
+      _create_page_toc(lines_to_scan, toc_lines)
+      markdown_lines.delete_at(page_toc_index)
+      markdown_lines.insert(page_toc_index, *toc_lines)
+    end
+    # Now review the markdown and include everything.
+    markdown_lines.each_with_index do |markdown_line, line_index|
+      match_data = markdown_line.match(INCLUDE_REGEXP)
+      unless match_data
+        output_lines.push(markdown_line)
+        next
+      end
+      treatment = match_data[1]
+      cited_includee_file_path = match_data[2]
+      new_inclusion = Inclusion.new(
+          markdown_line.chomp,
+          includer_file_path,
+          line_index + 1,
+          cited_includee_file_path,
+          treatment
+      )
+      inclusions.include(
+          new_inclusion,
           output_lines,
           self
       )
@@ -197,7 +217,7 @@ class MarkdownHelper
   end
 
   def self.git_clone_dir_path
-    git_dir = `git rev-parse --git-dir`.chomp
+    git_dir = `git rev-parse --show-toplevel`.chomp
     unless $?.success?
       message = <<EOT
 
@@ -206,71 +226,13 @@ That is, the working directory one of its parents must be a .git directory.
 EOT
       raise RuntimeError.new(message)
     end
-    if git_dir == '.git'
-      path = `pwd`.chomp
-    else
-      path = File.dirname(git_dir).chomp
-    end
-    realpath = Pathname.new(path.sub(%r|/c/|, 'C:/')).realpath
-    realpath.to_s
+    git_dir
   end
 
   def self.path_in_project(path)
     path.sub(MarkdownHelper.git_clone_dir_path + '/', '')
   end
 
-  def resolve_images(template_file_path, input_lines, output_lines)
-    input_lines.each do |input_line|
-      scan_data = input_line.scan(IMAGE_REGEXP)
-      if scan_data.empty?
-        output_lines.push(input_line)
-        next
-      end
-      output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
-      output_line = input_line
-      scan_data.each do |alt_text, path_and_attributes|
-        original_image_file_path, attributes_s = path_and_attributes.split(/\s?\|\s?/, 2)
-
-        # Attributes.
-        attributes = attributes_s ? attributes_s.split(/\s+/) : []
-        formatted_attributes = ['']
-        attributes.each do |attribute|
-          name, value = attribute.split('=', 2)
-          formatted_attributes.push(format('%s="%s"', name, value))
-        end
-        formatted_attributes_s = formatted_attributes.join(' ')
-
-        if original_image_file_path.start_with?('http')
-          image_path = original_image_file_path
-        else
-          absolute_template_file_path = File.absolute_path(template_file_path)
-          template_dir_path = File.dirname(absolute_template_file_path)
-          absolute_file_path = File.join(
-              template_dir_path,
-              original_image_file_path,
-          )
-          absolute_file_path = Pathname.new(absolute_file_path).cleanpath.to_s
-          relative_image_file_path = MarkdownHelper.path_in_project(absolute_file_path)
-          repo_user, repo_name = repo_user_and_name
-          image_path = File.join(
-              "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
-              relative_image_file_path,
-          )
-        end
-        img_element = format(
-            '<img src="%s" alt="%s"%s>',
-            image_path,
-            alt_text,
-            formatted_attributes_s,
-        )
-        output_line = output_line.sub(IMAGE_REGEXP, img_element)
-      end
-      output_lines.push(output_line)
-      output_lines.push(MarkdownHelper.comment(" <<<<<< END RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
-    end
-
-  end
-
   class Inclusions
 
     attr_accessor :inclusions
@@ -280,15 +242,11 @@ EOT
     end
 
     def include(
-        include_description,
-        includer_file_path,
-        includer_line_number,
-        cited_includee_file_path,
-        treatment,
-        output_lines,
-        markdown_helper
+      new_inclusion,
+      output_lines,
+      markdown_helper
     )
-      treatment = case treatment
+      treatment = case new_inclusion.treatment
                     when ':code_block'
                       :code_block
                     when ':markdown'
@@ -302,18 +260,12 @@ EOT
                     when ':pre'
                       :pre
                     else
-                      treatment
+                      new_inclusion.treatment
                   end
-      new_inclusion = Inclusion.new(
-          include_description,
-          includer_file_path,
-          includer_line_number,
-          cited_includee_file_path
-      )
       if treatment == :markdown
         check_circularity(new_inclusion)
       end
-      includee_path_in_project = MarkdownHelper.path_in_project(new_inclusion.absolute_includee_file_path)
+       includee_path_in_project = MarkdownHelper.path_in_project(new_inclusion.absolute_includee_file_path)
       output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{includee_path_in_project} ")) unless markdown_helper.pristine
       begin
         include_lines = File.readlines(new_inclusion.absolute_includee_file_path)
@@ -329,7 +281,7 @@ EOT
       end
       last_line = include_lines.last
       unless last_line && last_line.match("\n")
-        message = "Warning:  Included file has no trailing newline: #{cited_includee_file_path}"
+        message = "Warning:  Included file has no trailing newline: #{new_inclusion.cited_includee_file_path}"
         warn(message)
       end
       case treatment
@@ -346,7 +298,7 @@ EOT
           output_lines.push("</pre>\n")
         else
           # Use the file name as a label.
-          file_name_line = format("```%s```:\n", File.basename(cited_includee_file_path))
+          file_name_line = format("```%s```:\n", File.basename(new_inclusion.cited_includee_file_path))
           output_lines.push(file_name_line)
           # Put into code block.
           language = treatment == :code_block ? '' : treatment
@@ -389,65 +341,6 @@ EOT
       lines.join("\n")
     end
 
-    def self.assert_io_exception(test, expected_exception_class, expected_label, expected_file_path, e)
-      test.assert_kind_of(expected_exception_class, e)
-      lines = e.message.split("\n")
-      actual_label = lines.shift
-      test.assert_equal(expected_label, actual_label)
-      actual_file_path = lines.shift
-      test.assert_equal(expected_file_path.inspect, actual_file_path)
-    end
-
-    def self.assert_inclusion_exception(test, expected_exception_class, exception_label, expected_inclusions, e)
-      test.assert_kind_of(expected_exception_class, e)
-      lines = e.message.split("\n")
-      label_line = lines.shift
-      test.assert_equal(exception_label, label_line)
-      backtrace_line = lines.shift
-      test.assert_equal(BACKTRACE_LABEL, backtrace_line)
-      level_line_count = 1 + Inclusion::LINE_COUNT
-      level_count = lines.size / level_line_count
-      # Backtrace levels are innermost first, opposite of inclusions.
-      reversed_inclusions = expected_inclusions.inclusions.reverse
-      (0...level_count).each do |level_index|
-        level_line = lines.shift
-        inclusion_lines = lines.shift(Inclusion::LINE_COUNT)
-        test.assert_equal("#{LEVEL_LABEL} #{level_index}:", level_line)
-        expected_inclusion = reversed_inclusions[level_index]
-        expected_inclusion.assert_lines(test, level_index, inclusion_lines)
-      end
-    end
-
-    def self.assert_circular_exception(test, expected_inclusions, e)
-      self.assert_inclusion_exception(
-              test,
-              CircularIncludeError,
-              CIRCULAR_EXCEPTION_LABEL,
-              expected_inclusions,
-              e
-      )
-    end
-
-    def self.assert_includee_missing_exception(test, expected_inclusions, e)
-      self.assert_inclusion_exception(
-          test,
-          Exception,
-          MISSING_INCLUDEE_EXCEPTION_LABEL,
-          expected_inclusions,
-          e
-      )
-    end
-
-    def self.assert_template_exception(test, expected_file_path, e)
-      self.assert_io_exception(
-          test,
-          Exception,
-          UNREADABLE_INPUT_EXCEPTION_LABEL,
-          expected_file_path,
-          e
-      )
-    end
-
   end
 
   class Inclusion
@@ -460,19 +353,23 @@ EOT
       :include_description,
       :absolute_includee_file_path,
       :cited_includee_file_path,
-      :include_description
+      :treatment,
+      :page_toc_title,
+      :page_toc_line
 
     def initialize(
         include_description,
         includer_file_path,
         includer_line_number,
-        cited_includee_file_path
+        cited_includee_file_path,
+        treatment
     )
       self.include_description = include_description
       self.includer_file_path = includer_file_path
       self.includer_line_number = includer_line_number
       self.cited_includee_file_path = cited_includee_file_path
       self.absolute_includee_file_path = absolute_includee_file_path
+      self.treatment = treatment
       self.absolute_includee_file_path = File.absolute_path(File.join(
           File.dirname(includer_file_path),
           cited_includee_file_path,
@@ -485,10 +382,11 @@ EOT
       Pathname.new(absolute_includee_file_path).realpath.to_s
     end
 
+    def indentation(level)
+      '  ' * level
+    end
+
     def to_lines(indentation_level)
-      def indentation(level)
-        '  ' * level
-      end
       relative_inluder_file_path = MarkdownHelper.path_in_project(includer_file_path)
       relative_inludee_file_path = MarkdownHelper.path_in_project(absolute_includee_file_path)
        text = <<EOT
@@ -501,37 +399,6 @@ EOT
       text.split("\n")
     end
 
-    def assert_lines(test, level_index, actual_lines)
-      level_label = "Level #{level_index}:"
-      # Includer label.
-      includee_label = actual_lines.shift
-      test.assert_match(/^\s*Includer:$/, includee_label, level_label)
-      # Includer locatioin.
-      location = actual_lines.shift
-      message = "#{level_label} includer location"
-      test.assert_match(/^\s*Location:/, location, message)
-      includer_realpath =  Pathname.new(includer_file_path).realpath.to_s
-      relative_path = MarkdownHelper.path_in_project(includer_realpath)
-      r = Regexp.new(Regexp.escape("#{relative_path}:#{includer_line_number}") + '$')
-      test.assert_match(r, location, message)
-      # Include description.
-      description = actual_lines.shift
-      message = "#{level_label} include description"
-      test.assert_match(/^\s*Include description:/, description, message)
-      r = Regexp.new(Regexp.escape("#{include_description}") + '$')
-      test.assert_match(r, description, message)
-      # Includee label.
-      includee_label = actual_lines.shift
-      test.assert_match(/^\s*Includee:$/, includee_label, level_label)
-      # Includee file path.
-      includee_file_path = actual_lines.shift
-      message = "#{level_label} includee cited file path"
-      test.assert_match(/^\s*File path:/, includee_file_path, message)
-      relative_path = MarkdownHelper.path_in_project(absolute_includee_file_path)
-      r = Regexp.new(Regexp.escape("#{relative_path}") + '$')
-      test.assert_match(r, includee_file_path, message)
-    end
-
   end
 
 end