middleman-apps 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 07e504c02695ba4f0387c2d974c49030b12a0655
+  data.tar.gz: 46a2badf1b57e7572d6f71232999ce7783c8f50b
+SHA512:
+  metadata.gz: 110ab87281cb3a4109e9c3ef5b73d4db382a8622a7b34534b4b01ef31aaeab30af06e783bde2cccb727c9d043f32004eaf7d3e5227dfeafd00db1c293eff973e
+  data.tar.gz: 5f8a7f7edc8b1785e3ff7da9ace36d4e731c7ec01319256adea95d71cdf4f200e49ee6c7cb0b6a5b8ef84d1798d8d6f01a95cc2e826dacb7483d978efe225a8d

data/.gitignore

@@ -0,0 +1,8 @@
+# Ignore bundler lock file
+/Gemfile.lock
+
+# Ignore pkg folder
+/pkg
+
+/tmp
+/doc

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  Exclude:
+    - 'lib/middleman/apps/rack_contrib.rb'
+    - 'tmp/aruba'
+
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/middleman/apps/extension.rb'
+
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+- 2.4.0
+- 2.2.2      # rack 2.0 requires ruby >= 2.2.2

data/Gemfile

@@ -0,0 +1,19 @@
+# If you do not have OpenSSL installed, update
+# the following line to use "http://" instead
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in middleman-apps.gemspec
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rdoc'
+  gem 'yard'
+end
+
+group :test do
+  gem 'aruba'
+  gem 'capybara'
+  gem 'cucumber'
+  gem 'rspec'
+end

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Nikhil Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+## Middleman Apps
+
+`middleman-apps` is an extension for the [Middleman] static site
+generator that allows you to run truly dynamic pages within your static
+site using Rack-compatible (e.g. Sinatra) based child apps.
+
+You can create dynamic pages using this extension. Maybe you want to:
+
+- Create simple APIs that can be consumed by your static app via AJAX
+- Showcase Code snippets alongside your blog.
+- Provide simple Demos of a tech writeup, etc.
+- Display a dynamic Gallery of your most recent timeline from Flickr?
+- ... suggest one? ...
+
+The best way to get started with this extension is to have a look at the
+various `features` in the test suite. There is a test for each feature
+that exists for extension, such as:
+
+- Mount Rack apps by, simply, placing them in `MM_ROOT/apps` directory.
+- Allow running child apps in-tandem with the static (built) MM app, and
+  wrap them both in a single `Rack::App`, which can be run with e.g.
+  `rackup`.
+- Use a specific `404` error page that is common across your static
+  website, and child apps mounted using this extension.
+- Discovery of mountable child apps and automatic mounting.
+- Optionally, specify a URL where a child app should be mounted.
+- Optionally, specify a Class name or namespace for the child app.
+- Optionally, inherit from `Middleman::Apps::BaseApp` for helper methods
+  and added goodies for your apps.
+
+### Example
+
+You can, e.g. create a simple JSON API endpoint at: `/base64-api/`
+by creating a file named `apps/base64_api.rb` with:
+
+```ruby
+# config.rb
+...
+activate :apps
+...
+
+# apps/base64_api.rb
+require 'sinatra'
+class Base64Api < Sinatra::Base
+  get '/decode/:str' do
+    Base64.decode64(params['str'])
+  end
+  get '/encode/:str' do
+    Base64.encode64(params['str'])
+  end
+end
+```
+
+Run/Build your Middleman site now, and visit: 
+`/base64-api/encode/somestring`. Voila! It just works!
+
+A `config.ru` is, also, generated for you, so that you can keep
+using these dynamic pages/endpoints using `rackup`. Try running 
+`rackup`, and visiting the above endpoint on that server instance.
+
+## Installation
+
+If you're just getting started, install the `middleman` gem and generate
+a new project:
+
+```
+gem install middleman
+middleman init MY_PROJECT
+```
+
+If you already have a Middleman project: Add `gem "middleman-apps"`
+to your `Gemfile` and run `bundle install`.
+
+## Configuration
+
+```
+activate :apps,
+  map: {},               # Mappings for custom URL and Class for child apps
+  verbose: false,        # Display warnings if any when building main app
+  not_found: "404.html", # Render this page for 404 errors, if it exists
+  namespace: nil         # By default, use a namespace for finding Class
+                         # of a child app
+```
+
+A `config.ru` will be generated for you (if one does not exist already),
+when you preview/build your MM site. Your child apps will be mounted in
+both development (preview) mode (e.g. via `middleman server`) as well in
+production (build) mode of MM (e.g. running the built app using `puma`
+or `rackup`).
+
+## Options
+
+### `not_found: '404.html'`
+
+This option defines a custom HTML page to use for 404 errors. By
+default, HTML from `404.html` is served if it exists. Otherwise,
+a default 404 response is sent.
+
+A warning is generated in `verbose` mode, if this file does not exist!
+Set this option to `false`, if you prefer not to use a 404 page and
+would rather stick with default 404 response from Rack.
+
+### `verbose: false`
+
+If true, display warnings such as non-existent 404 error page, and any
+child apps that were ignored when starting server in
+development/production mode.
+
+### `namespace: nil`
+
+Specify a global namespace to find child apps in. Look at `map` option
+below for better clarification.
+
+### `map: {}`
+
+This option can be used to specify a custom URL endpoint for a specific
+child app, or different class name for your child app if different than
+what is guessed (`str.classify.constantize`).
+
+```ruby
+activate :apps,
+  namespace: 'DynamicPages',
+  map: {
+    test_app: 'test',
+    awesome_api: {
+      url: 'api',
+      class: "Project::AwesomeAPI"
+    }
+  }
+```
+
+With the above configuration in place, here is what happens:
+
+- class `DynamicPages::TestApp` should exist inside
+  `MM_ROOT/apps/test_app.rb` file, and it will be mounted at: `/test`
+  endpoint.
+
+- class `Project::AwesomeAPI` should exist inside
+  `MM_ROOT/apps/awesome_api.rb` file, and it will be mounted at: `/api`
+  endpoint.
+
+- If another child app `DynamicPages::OtherMiniProject` exists in:
+  `MM_ROOT/apps/other_mini_project.rb`, it will be mounted at:
+  `/other-mini-project` endpoint.
+
+## Community
+
+The official community forum is available at: http://forum.middlemanapp.com
+
+## Bug Reports
+
+Github Issues are used for managing bug reports and feature requests. If
+you run into issues, please search the issues and submit new problems:
+https://github.com/middleman/middleman-blog/issues
+
+The best way to get quick responses to your issues and swift fixes to
+your bugs is to submit detailed bug reports, include test cases and
+respond to developer questions in a timely manner. Even better, if you
+know Ruby, you can submit
+[Pull Requests](https://help.github.com/articles/using-pull-requests)
+containing Cucumber Features which describe how your feature should work
+or exploit the bug you are submitting.
+
+## How to Run Cucumber Tests
+
+- Checkout Repository:
+  `git clone https://github.com/nikhgupta/middleman-apps.git`
+
+- Install Bundler: `gem install bundler`
+
+- Run `bundle install` inside the project root to install the gem
+  dependencies.
+
+- Run test cases: `bundle exec rake test`
+
+## Donate
+
+[Click here to lend your support to Middleman](https://spacebox.io/s/4dXbHBorC3)
+
+## License
+
+Copyright (c) 2018 Nikhil Gupta. MIT Licensed, see [LICENSE] for details.
+
+[middleman]: http://middlemanapp.com
+[LICENSE]: https://github.com/nikhgupta/middleman-apps/blob/master/LICENSE.txt

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:cucumber, 'Run features that should pass') do |t|
+  t.cucumber_opts = '--color --tags ~@wip --strict'
+end
+
+require 'rake/clean'
+
+task test: ['cucumber']
+
+task default: :test

data/features/activation.feature

@@ -0,0 +1,53 @@
+Feature: Activating MiddlemanApps
+
+  Scenario: Without `middleman-apps`
+    Given a fixture app "simple-app"
+    And a file named "config.rb" with:
+      """
+      """
+    And the Server is running at "simple-app"
+    When I go to "/"
+    Then I should see "<h1>Middleman</h1>"
+    When I go to "/test-app"
+    Then the status code should be "404"
+    And  I should see "<h1>File Not Found</h1>"
+
+  Scenario: Without `middleman-apps` with Rack
+    Given a fixture app "simple-app"
+    And a file named "config.rb" with:
+      """
+      require 'sinatra'
+      require_relative 'apps/test_app'
+      map("/test-app") { run TestApp }
+      """
+    And the Server is running at "simple-app"
+    When I go to "/"
+    Then I should see "<h1>Middleman</h1>"
+    When I go to "/test-app"
+    Then I should see "fail"
+    When I go to "/test-app/?test=1"
+    Then I should see "pass"
+
+  Scenario: With `middleman-apps`
+    Given a fixture app "simple-app"
+    And a file named "config.rb" with:
+      """
+      activate :apps
+      """
+    And the Server is running at "simple-app"
+    When I go to "/"
+    Then I should see "<h1>Middleman</h1>"
+    When I go to "/test-app"
+    Then I should see "fail"
+    When I go to "/test-app/?test=1"
+    Then I should see "pass"
+
+  Scenario: Adds a `config.ru`
+    Given a fixture app "simple-app"
+    Then the file "config.ru" should not exist
+    Given a file named "config.rb" with:
+      """
+      activate :apps
+      """
+    And the Server is running at "simple-app"
+    Then the file "config.ru" should exist

data/features/build.feature

@@ -0,0 +1,20 @@
+Feature: Built app
+
+  Scenario: Builds successfully
+    Given a successfully built app at "simple-app"
+    Then the file "config.ru" should exist
+    And  the file "build/index.html" should exist
+    And  the file "build/apps/test_app.rb" should not exist
+
+  Scenario: Running built app
+    Given a fixture app "simple-app"
+    And   app is running with config:
+          """
+          activate :apps
+          """
+    When  I go to "/"
+    Then  I should see "<h1>Middleman</h1>"
+    When  I go to "/test-app"
+    Then  I should see "fail"
+    When  I go to "/test-app?test=1"
+    Then  I should see "pass"

data/features/child_app.feature

@@ -0,0 +1,18 @@
+Feature: 404 error pages for Child apps
+
+  Scenario: Custom 404 response from child app
+    Given a fixture app "complex-app"
+      And a file named "source/custom.html.erb" with:
+          """
+          <h2><%= 404 %> Custom Not Found!</h2>
+          """
+      And app is running with config:
+          """
+          activate :apps, not_found: "custom.html", namespace: :complex_app
+          """
+    When I go to "/child-app"
+    Then I should see "hello"
+    When I go to "/child-app/unknown"
+    Then the status code should be "404"
+    And  I should see "<h2>404 Custom Not Found!</h2>"
+

data/features/complex_app.feature

@@ -0,0 +1,66 @@
+Feature: Real world JSON API example
+
+  Scenario: Allows namespacing applications
+    Given a fixture app "complex-app"
+      And app is running with config:
+          """
+          activate :apps, namespace: "ComplexApp::SomeNamespace"
+          """
+    When I go to "/test-app?test=1"
+    Then the status code should be "200"
+    And  I should see "pass"
+
+  Scenario: Allows namespacing applications via underscored module path
+    Given a fixture app "complex-app"
+      And app is running with config:
+          """
+          activate :apps, namespace: "complex_app/some_namespace"
+          """
+    When I go to "/test-app?test=1"
+    Then the status code should be "200"
+    And  I should see "pass"
+
+  Scenario: Ignores modular apps that have no direct mapping
+    Given a fixture app "complex-app"
+      And app is running with config:
+          """
+          activate :apps, namespace: "other_namespacee"
+          """
+    When I go to "/test-app?test=1"
+    Then the status code should be "404"
+
+  Scenario: Allows specifying Application Name
+    Given a fixture app "complex-app"
+      And app is running with config:
+          """
+          activate :apps, namespace: :complex_app,
+            map: { child_app: "/some-other-path/abcd" }
+          """
+    When I go to "/some-other-path/abcd"
+    Then the status code should be "200"
+    And  I should see "hello"
+
+  Scenario: Allows specifying URL path for application
+    Given a fixture app "complex-app"
+      And app is running with config:
+          """
+          activate :apps,
+            namespace: 'complex_app/some_namespace',
+            map: {
+              test_app: 'test',
+              awesome_api: {
+                url: 'api',
+                class: "OtherNamespace::AwesomeAPI"
+              }
+            }
+          """
+    When I go to "/test-app?test=1"
+    Then the status code should be "404"
+    When I go to "/test?test=1"
+    Then the status code should be "200"
+    And  I should see "pass"
+    When I go to "/awesome-api/ping"
+    Then the status code should be "404"
+    When I go to "/api/ping"
+    Then the status code should be "200"
+    And  I should see "pong"

data/features/directory_indexes.feature

@@ -0,0 +1,52 @@
+Feature: Compatibility with other Extensions
+
+  # Use custom error page for `middleman-apps`:
+  # with Directory Indexes on - using `find_resource_by_path`
+  Scenario: Custom error page with Directory Indexes
+    Given a fixture app "simple-app"
+      And a file named "source/custom.html.erb" with:
+          """
+          <h2><%= 404 %> Custom Not Found!</h2>
+          """
+      And app is running with config:
+          """
+          activate :directory_indexes
+          activate :apps, not_found: "custom.html"
+          """
+    When I go to "/unknown-app"
+    Then the status code should be "404"
+    And  I should see "<h2>404 Custom Not Found!</h2>"
+
+  # Use custom error page for `middleman-apps`:
+  # with Directory Indexes on - using `find_resource_by_destination_path`
+  Scenario: Custom error page with Directory Indexes
+    Given a fixture app "simple-app"
+      And a file named "source/custom.html.erb" with:
+          """
+          <h2><%= 404 %> Custom Not Found!</h2>
+          """
+      And app is running with config:
+          """
+          activate :directory_indexes
+          activate :apps, not_found: "custom/index.html"
+          """
+    When I go to "/unknown-app"
+    Then the status code should be "404"
+    And  I should see "<h2>404 Custom Not Found!</h2>"
+
+  # Use custom error page for `middleman-apps`:
+  # with Directory Indexes on - using `find_resource_by_page_id`
+  Scenario: Custom error page with Directory Indexes
+    Given a fixture app "simple-app"
+      And a file named "source/custom.html.erb" with:
+          """
+          <h2><%= 404 %> Custom Not Found!</h2>
+          """
+      And app is running with config:
+          """
+          activate :directory_indexes
+          activate :apps, not_found: "custom"
+          """
+    When I go to "/unknown-app"
+    Then the status code should be "404"
+    And  I should see "<h2>404 Custom Not Found!</h2>"

data/features/not_found_rack.feature

@@ -0,0 +1,53 @@
+Feature: 404 error pages using Rack and MiddlemanApps
+
+  # Rack::NotFound's default response
+  Scenario: Default 404 response from Built app
+    Given a fixture app "simple-app"
+      And app is running
+     When I go to "/unknown-app"
+     Then the status code should be "404"
+      And I should see "Not found"
+
+  # Use default 404 error page for `middleman-apps`:
+  # Serve 404 pages from file: build/404.html
+  Scenario: 404 response from Built app when `404.html` exists
+    Given a fixture app "simple-app"
+      And a file named "source/404.html.erb" with:
+          """
+          <h1><%= (400+4).to_s + ' - Not Found' %></h1>
+          """
+      And app is running
+     When I go to "/unknown-app"
+     Then the status code should be "404"
+      And I should see "<h1>404 - Not Found</h1>"
+
+  # Use custom error page for `middleman-apps`:
+  Scenario: With a custom error page
+    Given a fixture app "simple-app"
+      And a file named "source/custom.html.erb" with:
+          """
+          <h2><%= 404 %> Custom Not Found!</h2>
+          """
+      And app is running with config:
+          """
+          activate :apps, not_found: "custom.html"
+          """
+    When I go to "/unknown-app"
+    Then the status code should be "404"
+    And  I should see "<h2>404 Custom Not Found!</h2>"
+
+  # Use custom error page for `middleman-apps`:
+  # Ensure that `build/404.html` is not being used for 404 pages now.
+  Scenario: No default 404 with custom error page
+    Given a fixture app "simple-app"
+      And a file named "source/404.html.erb" with:
+          """
+          <h1>Not Found</h1>
+          """
+      And app is running with config:
+          """
+          activate :apps, not_found: "custom.html"
+          """
+    When I go to "/unknown-app"
+    Then the status code should be "404"
+    And  I should see "Not found"

data/features/not_found_server.feature

@@ -0,0 +1,8 @@
+Feature: 404 error pages with Middleman Preview Server
+
+  Scenario: Fixed 404 response with Server
+    Given a fixture app "simple-app"
+    And the Server is running at "simple-app"
+    When I go to "/unknown-app"
+    Then the status code should be "404"
+    And  I should see "<h1>File Not Found</h1>"

data/features/step_definitions/rack_app_steps.rb

@@ -0,0 +1,15 @@
+Given(/app is running(?: with config:)?/) do |*args|
+  step %(I overwrite the file named "config.rb" with:), args[0] if args.any?
+  step %(I run `middleman build --verbose`)
+  step %(was successfully built)
+
+  app = nil
+  path = File.expand_path(expand_path('.'))
+  ENV['MM_ROOT'] = path
+
+  Dir.chdir(path) do
+    app, = Rack::Builder.parse_file('config.ru')
+  end
+
+  Capybara.app = app.to_app
+end

data/features/support/env.rb

@@ -0,0 +1,18 @@
+PROJECT_ROOT_PATH = File.dirname(File.dirname(File.dirname(__FILE__)))
+require 'middleman-core'
+require 'middleman-core/step_definitions'
+require File.join(PROJECT_ROOT_PATH, 'lib', 'middleman/apps')
+
+Before do
+  delete_environment_variable 'MM_ROOT'
+end
+
+module Aruba
+  module Platforms
+    # Turn off deprecation warnings from Aruba,
+    # atleast on my current system :)
+    class UnixPlatform
+      def deprecated(*_args); end
+    end
+  end
+end

data/features/verbose.feature

@@ -0,0 +1,23 @@
+Feature: Verbose mode
+
+  Scenario: Display list of child apps which were ignored
+    Given a fixture app "complex-app"
+      And I overwrite the file named "config.rb" with:
+          """
+          activate :apps, verbose: true
+          """
+      And I run `middleman build --verbose`
+      And the aruba exit timeout is 2 seconds
+      And I run `rackup -p 17283` in background
+     Then the output should match:
+          """
+          Ignored child app:.*apps\/awesome_api\.rb
+          """
+     And  the output should match:
+          """
+          Ignored child app:.*apps\/test_app\.rb
+          """
+     And  the output should match:
+          """
+          Ignored child app:.*apps\/child_app\.rb
+          """

data/fixtures/complex-app/apps/awesome_api.rb

@@ -0,0 +1,11 @@
+require 'sinatra'
+
+module OtherNamespace
+  # Child app that tests specifying a specific namespace/class
+  # for a single URL endpoint
+  class AwesomeAPI < Sinatra::Base
+    get '/ping' do
+      'pong'
+    end
+  end
+end

data/fixtures/complex-app/apps/child_app.rb

@@ -0,0 +1,15 @@
+require 'middleman/apps/base'
+
+module ComplexApp
+  # Child app that inherits from Middleman::Apps::BaseApp (which in turn
+  # inherits from Sinatra::Base) for additional features, such as:
+  # - error pages will be same as your main middleman static app
+  # - views and public folders set appropriately
+  # - handly helper methods, etc.
+  #
+  class ChildApp < ::Middleman::Apps::Base
+    get '/' do
+      'hello'
+    end
+  end
+end

data/fixtures/complex-app/apps/test_app.rb

@@ -0,0 +1,12 @@
+require 'sinatra'
+
+module ComplexApp
+  module SomeNamespace
+    # Child app that is used by option: namespace
+    class TestApp < Sinatra::Base
+      get '/' do
+        params[:test] ? 'pass' : 'fail'
+      end
+    end
+  end
+end

data/fixtures/complex-app/build/error.html

@@ -0,0 +1 @@
+<h1>Error!!</h1>

data/fixtures/complex-app/build/index.html

@@ -0,0 +1,2 @@
+<h1>Middleman</h1>
+

data/fixtures/complex-app/config.rb

@@ -0,0 +1 @@
+activate :apps # , not_found: 'error.html'

data/fixtures/complex-app/source/index.html.erb

@@ -0,0 +1,2 @@
+<h1>Middleman</h1>
+

data/fixtures/simple-app/apps/test_app.rb

@@ -0,0 +1,8 @@
+require 'sinatra'
+
+# Test application fixture
+class TestApp < Sinatra::Base
+  get '/' do
+    params[:test] ? 'pass' : 'fail'
+  end
+end

data/fixtures/simple-app/build/error.html

@@ -0,0 +1 @@
+<h1>Error!!</h1>

data/fixtures/simple-app/build/index.html

@@ -0,0 +1,2 @@
+<h1>Middleman</h1>
+

data/fixtures/simple-app/config.rb

@@ -0,0 +1 @@
+activate :apps # , not_found: 'error.html'

data/fixtures/simple-app/source/index.html.erb

@@ -0,0 +1,2 @@
+<h1>Middleman</h1>
+

data/lib/middleman.rb

@@ -0,0 +1 @@
+require 'middleman/apps'

data/lib/middleman/apps.rb

@@ -0,0 +1,65 @@
+require 'middleman-core'
+
+# Load extension nonetheless, as child apps may/will require this file.
+require 'middleman/apps/extension'
+
+# Register this extension with the name of `apps`
+Middleman::Extensions.register :apps, Middleman::Apps::Extension
+
+module Middleman
+  # Base namespace for `middleman-apps` extension.
+  #
+  module Apps
+    # Environment in which MM should be run
+    ENVIRONMENT = (ENV['MM_ENV'] || ENV['RACK_ENV'] || 'development').to_sym
+
+    # Middleman options that would be passed to create a reference instance.
+    MIDDLEMAN_OPTIONS = {
+      mode: :config,
+      watcher_disable: true,
+      exit_before_ready: true,
+      environment: ENVIRONMENT
+    }.freeze
+
+    # Middleman app instance for reference to configuration, etc.
+    #
+    # @return [Middleman::Application] an instance of {Middleman::Application}
+    #   using configuration in {MIDDLEMAN_OPTIONS}
+    #
+    def self.middleman_app
+      Middleman.setup_load_paths
+
+      ::Middleman::Application.new do
+        MIDDLEMAN_OPTIONS.each do |key, val|
+          config[key] = val
+        end
+      end
+    end
+
+    # Evaluate some code within the context of this extension.
+    #
+    # @param [Proc] block block to be executed
+    # @return [Any] - result of execution of the provided block
+    #
+    # @see .rack_app `.rack_app` method which uses this internally
+    #
+    def self.within_extension(&block)
+      app = middleman_app
+      options = app.extensions[:apps].options.to_h
+      Middleman::Apps::Extension.new(app, options).instance_eval(&block)
+    end
+
+    # Rack app comprising of the static (middleman) app with 404 pages, and
+    # child apps properly mounted.
+    #
+    # This method can be used directly to create a Rack app. Refer to the
+    # generated `config.ru` for an example.
+    #
+    # @return [Rack::App] rack application configuration
+    def self.rack_app
+      within_extension do
+        mount_child_apps(middleman_static_app)
+      end
+    end
+  end
+end

data/lib/middleman/apps/base.rb

@@ -0,0 +1,36 @@
+require 'sinatra'
+
+module Middleman
+  module Apps
+    # Base application class for creating child applications.
+    #
+    # Inheriting from this class should provide better syncronization with the
+    # static middleman app.
+    #
+    class Base < ::Sinatra::Base
+      # set :static, true
+
+      # set :mm_root, File.dirname(File.dirname(__FILE__))
+      # set :mm_dir, settings.development? ? 'source' : 'build'
+      # set :public_folder, File.join(settings.mm_root, settings.mm_dir)
+      # set :views, settings.public_folder
+
+      not_found do
+        send_file path_for_not_found, status: 404
+      end
+
+      protected
+
+      def middleman_app
+        Middleman::Apps.middleman_app
+      end
+
+      def path_for_not_found
+        Middleman::Apps.within_extension do
+          path = find_resource(options.not_found)
+          app.root_path.join(app.config.build_dir, path).to_s
+        end
+      end
+    end
+  end
+end

data/lib/middleman/apps/extension.rb

@@ -0,0 +1,231 @@
+require 'middleman-core'
+require 'middleman-core/load_paths'
+
+module Middleman
+  module Apps
+    # A Middleman extension to serve Rack applications (e.g. created via
+    # Sinatra) or other such apps when previewing using Middleman Preview
+    # server, as well as in the production (build) mode by creating an umbrella
+    # Rack app.
+    #
+    # Usage examples can be seen in README for this extension.
+    #
+    class Extension < ::Middleman::Extension
+
+      # @!group Options for Extension
+
+      # @!macro [attach] option
+      #   @!method $1(value)
+      #   Extension Option - $3 - Default: $2
+      #   @param value value for this option - Default: `$2`
+      option :not_found, '404.html', 'Path to 404 error page'
+      option :namespace, nil, 'Namespace for the child apps'
+      option :map, {}, 'Mappings for differently named child apps'
+      option :verbose, false, 'Displays list of child apps that were ignored'
+
+      # @!endgroup
+
+      def initialize(app, options_hash = {}, &block)
+        super
+        # useful for converting file names to ruby classes
+        require 'active_support/core_ext/string/inflections'
+      end
+
+      # Mount all child apps on a specific Rack app (or current app)
+      #
+      # @param [Rack::App] rack_app app on which to mount child apps
+      #                             Default: app from MM configuration
+      #
+      # @return [Rack::App] rack_app with child apps mounted on top
+      #
+      def mount_child_apps(rack_app = nil)
+        rack_app ||= app
+        child_apps.each do |url, klass|
+          rack_app.map(url) { run klass }
+        end
+        rack_app
+      end
+
+      # Get a hash of all child applications URLs paths matched to corresponding
+      # Ruby classes.
+      #
+      # Warning is raised (if `verbose` option is `true`) when a child app was
+      # found, but could not be mapped due to the specified config.
+      #
+      # @return [Hash] - child application URL vs Ruby class
+      #
+      def child_apps
+        apps_list.map do |mapp|
+          require mapp
+          klass = get_application_class_for(mapp)
+          warn "Ignored child app: #{mapp}" unless klass
+          [get_application_url_for(mapp), klass] if klass
+        end.compact.to_h
+      end
+
+      # Get a Rack::App that can serve the MM app's build directory.
+      #
+      # Directory paths, and 404 error page are deduced from extensions' options.
+      #
+      # @return [Rack::App] Rack::TryStatic app for MM app's build directory.
+      #
+      def middleman_static_app
+        not_found = options.not_found
+        return create_static_app(root) unless not_found
+
+        not_found_path = File.join(build_dir, find_resource(not_found))
+        create_static_app build_dir, not_found_path
+      end
+
+      # Get a list of all child apps that are found in `MM_ROOT/apps` directory.
+      #
+      def apps_list
+        pattern = File.join(app.root, 'apps', '*.rb')
+        Dir[pattern].map do |file|
+          File.realpath(file) if File.file?(file)
+        end.compact
+      end
+
+      # Run `after_configuration` hook passed on by MM
+      #
+      # After configuration for middleman has been finalized,
+      # create a `config.ru` in the root directory, and mount all child
+      # apps, if we are on a preview server.
+      #
+      # @return [nil]
+      #
+      # @private
+      # @api private
+      #
+      def after_configuration
+        create_config_ru
+        return unless app.server?
+        mount_child_apps(app)
+      end
+
+      # Create a `config.ru` file, if one does not exist, yet.
+      #
+      # This is done whenever `middleman` cli is run for building, or previewing
+      # the static app.
+      #
+      # @return [nil]
+      #
+      # @private
+      # @api private
+      #
+      def create_config_ru
+        path = File.join(app.root, 'config.ru')
+        return if File.exist?(path)
+
+        content = <<-CONTENT.gsub(/^ {6}/, '')
+        ENV['RACK_ENV'] = 'production'
+        require 'middleman/apps'
+        run Middleman::Apps.rack_app
+        CONTENT
+
+        File.open(path, 'wb') { |file| file.puts content }
+      end
+
+      # Create a Rack::TryStatic application for the given directory root.
+      #
+      # @param [String] root - path to directory root
+      # @param [String] path - path to not found error page
+      #                        If not provided, default 404 response from Rack
+      #                        is served.
+      #
+      # @return [Rack::App] static app for the `root` directory
+      #
+      # @api private
+      #
+      def create_static_app(root, path = nil)
+        unless File.exist?(path)
+          warn("Could not find: #{path}")
+          path = nil
+        end
+
+        # require 'rack/contrib'
+        require 'middleman/apps/rack_contrib'
+        ::Rack::Builder.new do
+          use ::Rack::TryStatic, urls: ['/'], root: root,
+            try: ['.html', 'index.html', '/index.html']
+          run ::Rack::NotFound.new(path)
+        end
+      end
+
+      # Find a resource given its path, destination path, or page_id.
+      #
+      # @param [String] name - identifier for this resource
+      # @return [String] relative path to resource
+      #
+      # @api private
+      #
+      def find_resource(name)
+        sitemap    = app.sitemap
+        resource   = sitemap.find_resource_by_path(name)
+        resource ||= sitemap.find_resource_by_destination_path(name)
+        resource ||= sitemap.find_resource_by_page_id(name)
+        resource ? resource.destination_path : name
+      end
+
+      private
+
+      # Warn user about message if `verbose` option is on.
+      #
+      # @param [String] message - message to display
+      #
+      # @private
+      # @api private
+      #
+      def warn(message)
+        logger.warn(message) if logger && options.verbose
+      end
+
+      # Get path to MM's build dir.
+      #
+      # @return [String] path to build dir
+      #
+      def build_dir
+        File.expand_path(app.config.build_dir.to_s)
+      end
+
+      # Convert options data to a hash for easy searches.
+      #
+      # @api private
+      # @return [Hash] options data
+      #
+      def mappings
+        options.map.map { |key, val| [key.to_s, val] }.to_h
+      end
+
+      # Get URL at which given child app should be mounted.
+      #
+      # @api private
+      # @param [String] file - path to child app
+      # @return [String] url component for the child app
+      #
+      def get_application_url_for(file)
+        name = File.basename(file, '.rb')
+        url  = mappings[name]
+        url  = url[:url] if url.is_a?(Hash)
+        '/' + (url ? url.to_s.gsub(%r{^\/}, '') : name.titleize.parameterize)
+      end
+
+      # Get Application Class for the child app.
+      #
+      # @api private
+      # @param [String] file - path to child app
+      # @return [Class, nil] Class for the child app, if exists.
+      #
+      def get_application_class_for(file)
+        name = File.basename(file, '.rb')
+        namespace = options.namespace
+
+        klass   = mappings[name][:class] if mappings[name].is_a?(Hash)
+        klass ||= namespace ? "#{namespace}/#{name}" : name
+        klass.to_s.classify.constantize
+      rescue NameError
+        return nil
+      end
+    end
+  end
+end

data/lib/middleman/apps/rack_contrib.rb

@@ -0,0 +1,77 @@
+# `rack-contrib` depends on `rack` v1.4, which is quite outdated now, and also,
+# limits us to Sinatra v1.4, while Sinatra v2.0 is out.
+#
+# Since, `middleman-apps` uses 2 tiny classes from `rack-contrib`, I copied them
+# here to remove `rack-contrib` from dependency list.
+#
+# Once `rack-contrib` supports `rack` v2.0, we can switch back to using it,
+# instead of this file.
+#
+# @todo
+#   [MAYBE] Merge the two Rack apps below into a single concise Rack app?
+module ::Rack
+
+  # The Rack::TryStatic middleware delegates requests to Rack::Static middleware
+  # trying to match a static file
+  #
+  # Examples
+  #
+  # use Rack::TryStatic,
+  #   :root => "public",  # static files root dir
+  #   :urls => %w[/],     # match all requests
+  #   :try => ['.html', 'index.html', '/index.html'] # try these postfixes sequentially
+  #
+  #   uses same options as Rack::Static with extra :try option which is an array
+  #   of postfixes to find desired file
+
+  class TryStatic
+
+    def initialize(app, options)
+      @app = app
+      @try = ['', *options[:try]]
+      @static = ::Rack::Static.new(
+        lambda { |_| [404, {}, []] },
+        options)
+    end
+
+    def call(env)
+      orig_path = env['PATH_INFO']
+      found = nil
+      @try.each do |path|
+        resp = @static.call(env.merge!({'PATH_INFO' => orig_path + path}))
+        break if !(403..405).include?(resp[0]) && found = resp
+      end
+      found or @app.call(env.merge!('PATH_INFO' => orig_path))
+    end
+  end
+
+  # Rack::NotFound is a default endpoint. Optionally initialize with the
+  # path to a custom 404 page, to override the standard response body.
+  #
+  # Examples:
+  #
+  # Serve default 404 response:
+  #   run Rack::NotFound.new
+  #
+  # Serve a custom 404 page:
+  #   run Rack::NotFound.new('path/to/your/404.html')
+
+  class NotFound
+    F = ::File
+
+    def initialize(path = nil, content_type = 'text/html')
+      if path.nil?
+        @content = "Not found\n"
+      else
+        @content = F.read(path)
+      end
+      @length = @content.size.to_s
+
+      @content_type = content_type
+    end
+
+    def call(env)
+      [404, {'Content-Type' => @content_type, 'Content-Length' => @length}, [@content]]
+    end
+  end
+end

data/lib/middleman/apps/version.rb

@@ -0,0 +1,5 @@
+module Middleman
+  module Apps
+    VERSION = '0.1.0'.freeze
+  end
+end

data/middleman-apps.gemspec

@@ -0,0 +1,27 @@
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+require 'middleman/apps/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'middleman-apps'
+  s.version     = Middleman::Apps::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Nikhil Gupta']
+  s.email       = ['me@nikhgupta.com']
+  s.homepage    = 'https://github.com/nikhgupta/middleman-apps'
+  s.summary     = 'Middleman extension to run dynamic pages using Sinatra'
+  s.description = 'Middleman extension to run dynamic pages using Sinatra'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ['lib']
+  s.executables   = `git ls-files -- bin/*`.split("\n").map do |f|
+    File.basename(f)
+  end
+
+  s.add_runtime_dependency('middleman-core', ['~> 4.2'])
+  s.add_runtime_dependency('sinatra', ['~> 2.0'])
+  s.add_runtime_dependency('activesupport', ['>= 4.2'])
+  # s.add_runtime_dependency('rack-contrib', ['>= 1.7.0'])
+
+  s.add_development_dependency('middleman-cli')
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: middleman-apps
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nikhil Gupta
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: middleman-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: middleman-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Middleman extension to run dynamic pages using Sinatra
+email:
+- me@nikhgupta.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- features/activation.feature
+- features/build.feature
+- features/child_app.feature
+- features/complex_app.feature
+- features/directory_indexes.feature
+- features/not_found_rack.feature
+- features/not_found_server.feature
+- features/step_definitions/rack_app_steps.rb
+- features/support/env.rb
+- features/verbose.feature
+- fixtures/complex-app/apps/awesome_api.rb
+- fixtures/complex-app/apps/child_app.rb
+- fixtures/complex-app/apps/test_app.rb
+- fixtures/complex-app/build/error.html
+- fixtures/complex-app/build/index.html
+- fixtures/complex-app/config.rb
+- fixtures/complex-app/source/index.html.erb
+- fixtures/simple-app/apps/test_app.rb
+- fixtures/simple-app/build/error.html
+- fixtures/simple-app/build/index.html
+- fixtures/simple-app/config.rb
+- fixtures/simple-app/source/index.html.erb
+- lib/middleman.rb
+- lib/middleman/apps.rb
+- lib/middleman/apps/base.rb
+- lib/middleman/apps/extension.rb
+- lib/middleman/apps/rack_contrib.rb
+- lib/middleman/apps/version.rb
+- middleman-apps.gemspec
+homepage: https://github.com/nikhgupta/middleman-apps
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Middleman extension to run dynamic pages using Sinatra
+test_files:
+- features/activation.feature
+- features/build.feature
+- features/child_app.feature
+- features/complex_app.feature
+- features/directory_indexes.feature
+- features/not_found_rack.feature
+- features/not_found_server.feature
+- features/step_definitions/rack_app_steps.rb
+- features/support/env.rb
+- features/verbose.feature