xstatic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b69b5953ca4db2d64161ef0bc093227368c6bebb710efd9b5967da0d82fa8e27
+  data.tar.gz: 35ecaa8dad413c97c7009fa7cda3b5456e904996b564217af3e84cc804da7def
+SHA512:
+  metadata.gz: 293657fcc5dcc1f02031c6854aeadafc253434087ae48ab1d1bf71b38a4b5f6c342abf861aea643ac507376e8408ea8b9ebef6cd232a038dc6c5a161173a2658
+  data.tar.gz: b3c058b68184c0caad38d6bc80486ca59a778fd187907a92b93b54499262de5749410aa99b7ad9b3a0ea0a3d46d5daa576a4c85e858cc869e26d93ada6134f6f

data/DESIGN.rdoc

@@ -0,0 +1,173 @@
+= XStatic Design Notes
+
+This is the ruby version of Staticizer. It uses a similar method as the Mote
+gem to parse ERB files very quickly.
+
+See the m4/C version in ~/work/staticizer-m4/Readme for details.
+
+== Pros & Cons: Staticizer vs. SSI
+
+While researching for a simpler way to build websites, I explored the plethora
+of static site generators. Most are overly engineered. Others seem easy from
+the user's perspective, but are complex under the hood. I also wanted something
+with minimal dependencies, and preferably existing and standard tools.
+
+So I decided to build my own using make(1) and m4(1). It worked and is super
+fast. The problem is that is is difficult to understand the m4 language. Plus
+it was not as flexible or extendible as something built with an interpreted
+language like ruby. Awk could be a possibility but I never explored it.
+
+Then I decided to reimplement the make/m4 system using rake/ruby. It's very
+nice, easy to use with a simple and straightforward implementation. It would
+also be very easy to add features, even though I haven't done it.
+
+The one problem with both of these systems is dependency. An HTML page is
+constructed from the content (markdown, html, erb), which is encapsulated in a
+layout. Optionally, the content and layout may include templates. The
+dependency problem occurs when a template is updated, how to update the content
+and layouts that may depend on it? I know make and rake are supposed to handle
+this stuff, but it requires manual intervention to assign the dependencies.
+This leaves lots of room for human error.
+
+Not satisfied, I decided to keep looking for an answer. I was reminded of
+server-side includes (SSI). I had used them 20 years ago but jumped on the Ruby
+on Rails bandwagon and just forgot. After revisiting SSI, I think this may
+satisfy my requirements and deal with the dependency issue. They inherently
+solve the dependency issue by compiling the page "parts" on the fly. For
+example, if a template is updated, any page content or layout that depends on
+it will simply include the new version on the next request. That's it!
+
+But SSI is not without problems. It compiles HTML, not markdown, in which some
+of my content is formatted. So a processing step would be required, which
+diminishes its advantage over the make/m4 and rake/ruby systems. Therefore SSI
+doesn't have a dependency problem but does require some preprocessing, which m4
+and ruby do.
+
+A notable issue with SSI is the web server configuration. It's not as friendly
+or accessible as a makefile. For example, encapsulating a set of pages in a
+layout would be specified in the web server routing rules (e.g., location
+directive in nginx).
+
+But the biggest problem with SSI is that, unlike the other systems, variables
+are only in-scope at the point of definition or inclusion. For example, a title
+in head cannot be set by a variable defined at the page-content level. The m4
+processor solves this by ordering buffers. Ruby solves this with binding and
+runtime evaluation. The only way I see to solve this in SSI is to parse the
+include files and generate a "meta" file that would be included at the top of
+the document.
+
+SSI also lacks the programming power of a language like Ruby. This power can be
+used for good. For example, auto-generating figure numbers and references
+within a technical document. This could probably be solved with SSI variables,
+but I think it would get ugly.
+
+Statically generating HTML pages provides maximum portability. Any web server
+can serve them. However, SSI is much less portable. The SSI directives are
+somewhat similar between nginx and Apache; but other servers, like OpenBSD's
+httpd, don't support them. The bigger problem is that web server configurations
+are all unique.
+
+A very powerful feature of SSI is the inclusion of a request. This provides a
+static page with dynamic elements. A drawback is client-side caching. If the
+page were cached then the dynamic effect would be lost. I guess this is where
+client-side Javascript is the answer.
+
+A possibly minor disadvantage of SSI over static pages is performance. The web
+server is parsing—perhaps requesting virtual includes—and compiling complete
+pages on the fly. However, nginx does provide some caching solutions, but this
+is just more complexity.
+
+An example SSI configuration with good presentation and content separation is
+<https://www.nginx.com/resources/wiki/start/topics/examples/dynamic_ssi/>.
+
+A cool benefit of the rake system is that it scans the page sources looking for
+templates to add as dependencies, and, if a template doesn't actually exist it
+complains.
+
+*Idea*: could the include directive virtually request a markdown page, which
+will get compiled on the fly? That would be kind of cool.
+
+
+== Page & Template Processing
+
+The problem with variables in XML comments (<!-- -->) and processing
+instructions (<? ?>) in markdown is that kramdown will output them. Erb
+processing cannot use such instructions. Alternatively, when using the Erb
+processing instructions (<% %>), kramdown entity encodes the tags.
+
+The immediate solution is to process with Erb first then kramdown. The only
+problem with this is that Erb may be processing all of the markdown only for
+a few variables at the top, or worse, for no reason at all. This could be
+optimized later by only reading the beginning of the file where the code
+block must be, then pass the rest of the file on to kramdown. A flag could be
+set in the preamble that indicates if the rest of the file should be processed
+by Erb or not. This could improve performance but would require more logic.
+
+When processing markdown content, first run Erb to evaluate all processing
+instructions. Erb processing instructions may evaluate to html or additional
+markdown—either of which kramdown can manage. Then kramdown converts to html.
+Finally, the page renders with a layout.
+
+== Indexing & Search
+
+At some point, need to add a search feature.
+Start at <https://en.wikipedia.org/wiki/Search_engine_indexing>.
+Should probably index or parse the final HTML files. It's tempting to parse the
+markdown files directly because they are simple, but this would complicate the
+search engine because then it would also have to be adapted to search HTML,
+Erb, etc. Plus, HTML has additional semantics.
+
+Been thinking about how to do this, but never got serious about it. While
+researching email clients, I ran across [Notmuch](https://notmuchmail.org)
+which is an email search utility used by Mutt and others. Notmuch uses Xapian
+under the hood. The port mail/mu is a searcher that also uses Xapian.
+
+[Xapian](https://xapian.org) is a highly adaptable toolkit which allows
+developers to easily add advanced indexing and search facilities to their own
+applications. It is written in C++ and has many bindings, including Lua, Ruby,
+and Tcl.
+
+== Changed Resources
+
+What if a style sheet or script changes? How will the layouts or pages that
+depend on them get updated?
+
+Changes in CSS, Javascript, or other externally linked resources is not
+particularly in XStatic's domain. This is the concern of HTML linking and HTTP
+caching. XStatic is unaware of the relationship between these linked resources.
+However, to serve new versions of such resources, XStatic can help overcome
+long cache times.
+
+One solution is to add or update a version parameter to the resource's URL.
+That will trigger a rebuild of the page, which updates the last-modified and
+etag headers sent by the HTTP server. With a proper cache configuration, the
+client will request the new version of the resource.
+
+== Path Name Conflicts Within the HTML Directory
+
+Page names may conflict with directory or asset names or another page with the
+same name but a different extension. A rendered page is stored in an
+extensionless filename under the HTML site directory. For example, if there is
+a directory named "book", then a page named "book.md" within the same directory
+will conflict.
+
+    content/
+        book.md
+        book/
+            chapter1
+            chapter2
+
+The page "book.md" and the directory "book/" will have the same path name under
+the HTML site directory. To resolve this, move "book.md" to an index file under
+the "book/" directory.
+
+    content/
+        book/
+            index.md
+            chapter1
+            chapter2
+
+Likewise, the pages "foobar.md" and "foobar.erb" within the same directory will
+conflict (i.e., they both render as the HTML file "foobar"). All markdown is
+preprocessed with Erb first; using "book.md" will suffice.
+

data/README.rdoc

@@ -0,0 +1,88 @@
+= XStatic—Smart Static Site Generator
+
+A smart, static site generator that automatically manages dependencies to
+achieve blazing build times with minimal cognitive load. Only new and changed
+files, and files upstream of a changed dependency are processed. Renders
+markdown or embedded-Ruby (Erb-like) content as HTML.
+
+Supports templates (embedded & layout), which may be included within content
+sources or other templates. Document metadata may me added using a plain-text
+preamble of key-value pairs. Generates a complete website that can be served by
+the built-in WEBrick server.
+
+XStatic is just a _Rake_ application with some magic sprinkled on top.
+
+Markdown and Erb content are transformed with a custom Erb processor. This
+allows you to add application logic to your markdown content, for example fetch
+records from a database. All other content, such as HTML, CSS, and images, are
+hard linked to the destination directory, ready to be served or copied to a
+remove production server.
+
+== Examples
+
+Here's an example command sequence to get a project up and running.
+
+  $ mkdir myproject
+  $ cd myproject
+  
+  $ xstatic init                    # set up initial project files
+  $ find . -type f
+  ./content/index.md                # markdown content & metadata
+  ./content/default.css             # asset to be hard linked under ./site
+  ./templates/layouts/default.erb   # layout template used to render index
+
+  $ xstatic site                    # build website under ./site
+  updated ./site/index              # markdown & metadata converted to HTML
+  $ find ./site
+  ./site                            # complete static site ready to be served
+  ./site/index                      # generated HTML file
+  ./site/default.css                # hard linked asset
+
+  $ xstatic start                   # start WEBrick server on port 2000
+  $ xstatic stop                    # stop WEBrick server
+
+The above sequence can be simplified to a single command:
+
+  $ xstatic init site start         # and you're ready to go!
+
+== Site Development Process
+
+Just follow this simple 5-step process as you build your site:
+
+1. Add assets and content to the *content* directory.
+2. Factor out code and data (HTML, Erb, markdown, plain text, etc.) to the
+   *templates* directory.
+3. Create custom layouts in the *templates/layouts* directory.
+4. Update the site by running +xstatic+.
+5. Reload *localhost:2000* in your browser to see your changes.
+
+
+== Links
+
+Homepage      :: https://ecentryx.com/gems/xstatic
+Ruby Gem      :: https://rubygems.org/gems/xstatic
+
+
+== History
+
+1. 2022-02-24, v0.1.0
+   * First public release.
+
+
+== License
+
+({ISC License}[https://opensource.org/licenses/ISC])
+
+Copyright (c) 2022, Clint Pachl <pachl@ecentryx.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/Rakefile

@@ -0,0 +1,25 @@
+gemspec = eval File.read(Dir['*.gemspec'].first)
+
+require 'rubygems/package_task'
+Gem::PackageTask.new(gemspec) {}
+
+require 'rdoc/task'
+RDoc::Task.new(
+  rdoc:         'doc',
+  rerdoc:       'doc:force',
+  clobber_rdoc: 'doc:clean'
+) do |doc|
+  doc.rdoc_dir = 'doc'
+  doc.rdoc_files = gemspec.extra_rdoc_files
+  doc.options = gemspec.rdoc_options
+end
+
+desc 'Publish RDoc HTML files'
+task 'doc:pub' => 'doc' do
+  dir  = ENV['public_gem_dir'] + gemspec.name
+  host = ENV['public_gem_host']
+  `cd ./doc && pax -w . | ssh #{host} 'cd #{dir} && rm -rf * && pax -r'`
+end
+
+require 'rake/testtask'
+Rake::TestTask.new

data/TODO

@@ -0,0 +1,48 @@
+# XStatic To-Do #
+
+* Dependencies between templates is not implemented; only pages-to-templates
+  and layouts-to-templates dependencies are implemented. Layouts are just
+  templates that reside in the "layouts" directory under the main templates
+  directory.
+
+  For example, if a layout (a template) includes Javascript code (via a
+  template), and the Javascript is modified, none of the pages that depend on
+  that layout will be updated with the new Javascript code.
+
+  I actually implemented this on 6/1/21 using a FileList block just for
+  layouts only, not other non-layout templates. Could just as easily add it
+  for all types of templates, but will just test this first. Plus non-layout
+  to non-layout template dependencies are probably rare. There was no
+  measurable difference when adding 3 layouts; could probably just FileList
+  the entire TEMPLATES dir without a slow down.
+
+* Add tests.
+
+* Add configuration file.
+
+
+## HTMLPage Class To-Do
+
+* Because templates and layouts may be used by multiple pages, *cache* them
+  within thread like Mote. No need to cache the page sources because they are
+  not re-evaluated. Do no prematurely optimize.
+
+* It may be useful to pass local variables into a template. For example, to set
+  the title of a template:
+
+      template "comment_form.html", title: "Your Feedback"
+
+  This change would require a params to #transform, like Mote. 
+
+* Add method to allow adding `<link>` tags to `<head>` (via @page?).
+  For example:
+
+      link_tag href: 'http://example', rel: 'stylesheet'
+      page.link 'http://example', rel: 'stylesheet'
+      link 'http://example', 'stylesheet'
+
+  See:
+
+    - https://html.spec.whatwg.org/multipage/links.html#linkTypes
+    - https://ogp.me/
+

data/bin/xstatic

@@ -0,0 +1,321 @@
+#!/usr/bin/env ruby
+#
+# XStatic is a rake-driven application.
+#
+# - Dependency chains are managed by rake.
+# - HTML generation and Erb processing is managed by the class HTMLPage.
+# - Markdown processing is manged by kramdown.
+# - WEBrick is the HTTP server.
+
+
+### Configuration ###
+
+APP  = File.basename($0)
+ADDR = ENV['host'] || 'localhost' # web server hostname or IP address
+PORT = ENV['port'] || 2000        # web server port
+DST       = "./site"              # destination of website build: assets+pages
+SRC       = "./content"           # sources used to generate html pages
+ASSETS    = "./content"           # static files; e.g. scripts, styles, images
+TEMPLATES = "./templates"         # inline templates for pages and layouts
+LAYOUTS   = "./templates/layouts" # special templates used to render pages
+LOG       = "./LOG"               # web server stdout/stderr; see :start task
+Pages     = []                    # html page targets to be built
+
+# default project files; see task :init
+INDEX_FILE  = SRC     + '/index.md'
+LAYOUT_FILE = LAYOUTS + '/default.erb'
+STYLE_FILE  = ASSETS  + '/default.css'
+
+INLINE_TEMPLATE_RE = /(?:^|<)%= ?template ['"](.*?)["']/
+ACCESS_LOG_FORMAT  = "[%{%F %T}t] %s %a %m %U" # see webrick/accesslog.rb
+
+require 'html_page'
+require 'rake'
+Rake.application.init(APP)
+TASKS = Rake.application.top_level_tasks.to_s
+verbose false                     # silence FileUtils
+
+
+### Page & Layout Targets ###
+
+def build_html_target(source, layout_name, templates = [])
+  prerequisites = [source]  # erb/md source for html build target
+
+  if layout_name
+    layout = File.join(LAYOUTS, layout_name + '.erb')
+    unless File.exist? layout
+      warn "No such file `#{layout}'.\nCheck `Layout' in #{source}."
+      exit 2
+    end
+    prerequisites << layout
+  end
+
+  templates.each {|t| prerequisites << File.join(TEMPLATES, t) }
+  target = source.pathmap("%{^#{SRC},#{DST}}X") # make html files extensionless
+
+  #puts "#{target}: #{templates << layout}" if DEBUG # for debugging
+
+  file(target => prerequisites) do
+    begin
+      content = HTMLPage.new(source, layout).render
+    rescue => e
+      warn "#{e.class} in source file `#{source}'."
+      warn e.message
+      raise #if DEBUG
+      exit 3
+    end
+
+    if File.write(target, content) < 1
+      warn "cannot write #{target}"
+      exit 2
+    else
+      puts "updated #{target}"
+    end
+  end
+
+  return target
+end
+
+FileList["#{SRC}/**/*.{erb,md}"].each do |source|
+  f = File.new(source)
+  layout = 'default'
+
+  10.times do # only read preamble lines to retrieve layout
+    line = f.gets
+    break unless line
+    name, sep, value = line.partition(':')
+
+    if sep == ':' && name.downcase == 'layout'
+      layout = value.strip
+      layout = nil if layout.empty?
+      break
+    end
+  end
+
+  f.rewind
+  templates = f.read.scan(INLINE_TEMPLATE_RE).flatten
+  f.close
+
+  Pages << build_html_target(source, layout, templates)
+end
+
+FileList["#{LAYOUTS}/**/*.erb"].each do |layout|
+  templates = File.read(layout).scan(INLINE_TEMPLATE_RE).flatten
+  if templates.size > 0
+    prerequisites = templates.map {|t| File.join(TEMPLATES, t)}
+    file(layout => prerequisites)
+  end
+end
+
+
+### Initialization Tasks ###
+
+desc "create project"
+task :init => [INDEX_FILE, STYLE_FILE, LAYOUT_FILE] do
+  # Must manually build HTML target to support multi-target `init site`.
+  if TASKS =~ /"(pages|site)"/
+    index = build_html_target(INDEX_FILE, 'default')
+    Rake::Task[DST].execute
+    Rake::Task[index].execute
+  end
+end
+
+directory DST
+directory SRC
+directory ASSETS
+directory TEMPLATES
+directory LAYOUTS
+
+file(INDEX_FILE => SRC) {|t| File.write(t.name, <<EOF) }
+Title:       XStatic Project
+Keywords:    static website generator, html site builder, markdown templates
+Description: XStatic is a static website generator.
+
+# XStatic—Static Site Generator
+
+Web pages are written in markdown (.md) or Ruby-flavored HTML (.erb).
+Learn more about the syntax of these two markup languages:
+
+  * [Markdown syntax](https://www.markdownguide.org/basic-syntax/)
+  * [ERB templates](https://docs.ruby-lang.org/en/master/ERB.html)
+EOF
+
+file(LAYOUT_FILE => LAYOUTS) {|t| File.write(t.name, <<EOF) }
+<!DOCTYPE html>
+<html lang=en-US>
+<head>
+	<meta charset=utf-8>
+	<!-- STYLES, FONTS, ICONS -->
+	<link rel=preload href=/MY-FONT.woff2 as=font type=font/woff2 crossorigin>
+	<link rel=preload href=#{STYLE_FILE.delete_prefix ASSETS} as=style>
+	<link rel=stylesheet media=screen href=#{STYLE_FILE.delete_prefix ASSETS}>
+	<link rel=icon sizes=any href=/MY-ICON.svg type="image/svg+xml">
+	<link rel=apple-touch-icon href=/MY-ICON.png> <!-- 180x180 px PNG -->
+	<!-- MOBILE META -->
+	<meta name=viewport content="width=device-width,initial-scale=1">
+	<meta name=theme-color content=black>
+	<meta name=application-name content="MY-APP NAME ON ANDROID">
+	<meta name=apple-mobile-web-app-title content="MY-APP NAME ON APPLE">
+	<!-- DOCUMENT META -->
+	<meta name=author content="<%= page.author || 'MY NAME' %>">
+	<meta name=keywords content="<%= page.keywords %>">
+	<meta name=description content="<%= page.description %>">
+	<title><%= page.title %></title>
+</head>
+<body>
+	<header>
+		<nav>
+			<ul>
+				<li><a href="/">Home</a></li>
+				<li><a href="/link1">Link 1</a></li>
+				<li><a href="/link2">Link 2</a></li>
+			</ul>
+		</nav>
+	</header>
+	<main>
+    <%= page.content %>
+	</main>
+	<footer>
+		<nav>
+			<ul>
+				<li><a href="/link3">Link 3</a></li>
+				<li><a href="/link4">Link 4</a></li>
+			</ul>
+		</nav>
+		<div id=copyright>© <%= Time.now.year %> Your Name</div>
+	</footer>
+</body>
+</html>
+EOF
+
+file(STYLE_FILE => ASSETS) {|t| File.write(t.name, <<EOF) }
+body {
+	margin: 0;
+	padding: 0;
+}
+main {
+	margin: 2em auto;
+	max-width: 70ch;
+}
+nav ul {
+	margin: 1em auto;
+	max-width: 70ch;
+	padding: 0;
+}
+nav li {
+	display: inline;
+	padding: 1em;
+}
+body > header {
+	border-bottom: solid 1px silver;
+	text-align: right;
+}
+body > footer {
+	border-top: solid 1px silver;
+	text-align: center;
+}
+#copyright {
+	color: gray;
+	font-style: italic; 
+}
+EOF
+
+
+### Content Management Tasks ###
+
+desc "build website [assets + pages] (default)"
+task :site => [:assets, :pages]
+task :default => :site
+
+desc "update assets"
+task :assets => [:is_initialized, ASSETS, DST] do
+  ignore = '-name ".*.sw?"' # vim swap
+  if ASSETS == SRC  # ignore source files when under same directory
+    ignore << ' -o -name "*.md" -o -name "*.erb"'
+  end
+  %x[cd #{ASSETS} && find . ! \\( #{ignore} \\) | cpio -pl ../#{DST}]
+end
+
+desc "update pages"
+task :pages => [:is_initialized, :page_dirs, *Pages]
+
+# make all page directories
+task :page_dirs => [SRC, DST] do
+  %x[(cd #{SRC} && find . -type d) | (cd #{DST} && xargs mkdir -p)]
+end
+
+desc "remove website [#{DST}]"
+task :clean => [:is_initialized] do
+  rm_rf DST
+end
+
+task :is_initialized do
+  [ASSETS, SRC, TEMPLATES, LAYOUTS].each do |dir|
+    unless Dir.exist? dir
+      puts "Try `#{APP} init` or `#{APP} --tasks`"
+      exit 1
+    end
+  end
+end
+
+
+### Web Server Tasks ###
+
+desc "start web server [#{ADDR}:#{PORT}]"
+task :start do
+  if File.exist? LOG
+    pid, port = File.read(LOG).scan(/pid=([0-9]+) port=([0-9]+)/)[0]
+
+    if pid
+      begin
+        Process.kill(0, pid.to_i) # check if running; see kill(1)
+        puts "Web server running with pid #{pid} on port #{port}."
+        exit 0
+      rescue Errno::ESRCH
+        puts "Web server shutdown improperly; restarting on port #{PORT}."
+      end
+    end
+  end
+
+  require 'webrick'
+
+  module WEBrick::HTTPUtils
+    # Set default content type to html for extentionless files.
+    def self.mime_type(filename, mime_tab)
+      ext = File.extname(filename)[1..]&.downcase
+      mime_tab[ext || 'html']
+    end
+  end
+
+  log_file = File.open(File.absolute_path(LOG), 'w')
+  log_file.sync = true
+
+  server = WEBrick::HTTPServer.new(
+    :AccessLog      => [[log_file, ACCESS_LOG_FORMAT]],
+    :Logger         => WEBrick::Log.new(log_file),
+    :DirectoryIndex => %w(index index.html),
+    :DocumentRoot   => File.absolute_path(DST),
+    :BindAddress    => ADDR,
+    :Port           => PORT
+  )
+  begin
+    WEBrick::Daemon.start
+    server.start
+  ensure
+    server.shutdown
+    log_file.close
+    File.unlink(log_file.path)
+  end
+end
+
+desc "stop web server"
+task :stop do
+  if File.exists? LOG
+    pid = File.read(LOG)[/pid=([0-9]+)/, 1]
+    Process.kill('TERM', pid.to_i) if pid
+  end
+end
+
+
+# Run specified rake tasks.
+Rake.application.top_level

data/lib/html_page.rb

@@ -0,0 +1,193 @@
+require 'kramdown'  # markdown converter
+
+class HTMLPage
+
+  # user-defined attributes
+  Attributes = %i(author description keywords layout robots title)
+
+  # page attributes are available to templates
+  PageAttributes = Struct.new(*Attributes, :content)
+  attr_reader :page
+
+  TEMPLATES_DIR = './templates/'
+
+  #
+  # Compile an HTML page from the +content_filename+ and +layout_filename+
+  # sources.
+  #
+  # Content files must be markdown or embedded ruby and have an "md" or "erb"
+  # extension. If markdown, content is first evaluated as Erb. Layouts files
+  # must be "erb". The content renders within the layout template if specified.
+  #
+  # Attributes specified in the preamble of the content file will be set in
+  # +page+ and are available to layout and embedded templates. 
+  #
+  def initialize(content_filename, layout_filename = nil)
+    @content_filename = content_filename
+    @layout_filename  = layout_filename&.delete_prefix(TEMPLATES_DIR)
+    @page = PageAttributes.new
+  end
+
+  #
+  # Returns the rendered HTML page.
+  #
+  def render
+    f = File.new(@content_filename)
+
+    # parse attributes and content
+    while (line = f.gets)
+      case line
+      when /^(\w+):(.*)/  # begin attribute
+        begin
+          attribute = page[$1.downcase] = $2.strip
+        rescue NameError => e
+          raise e.class, "Bad page attribute `#{$1}'.\n"\
+            "Valid attributes: #{Attributes.to_s.tr('[:]','')}"
+        end
+      when /^\s*$/        # end attribute (blank lines between attrs)
+        attribute = nil
+      else
+        unless attribute  # remainder is content
+          content = line
+          content << f.gets(nil) unless f.eof?
+          break
+        end
+        attribute << (attribute.empty? ? '':' ') << line.strip
+      end
+    end
+
+    f.close
+    content = instance_eval(transform(content)).call # process with erb
+
+    if @content_filename.end_with? '.md'
+      if page.title.nil? # then use H1
+        page.title = content[/^#\s+([^#\{\r\n]+)/, 1]&.rstrip
+      end
+      opts = { auto_ids: false }
+      content = Kramdown::Document.new(content, opts).to_html
+    end
+
+    if @layout_filename
+      page.content = content
+      template(@layout_filename) # page.content embedded in layout
+    else
+      content # without a layout
+    end
+  end
+
+
+  private
+
+  ERB_EVAL_OPERATORS = /
+    ^(%)\s+(.*?)(?:\n|\Z) | #  %  single line of code
+    ^(%=)(.*?)(?:\n|\Z)   | #  %= single line of code output as string
+    (<%)\s+(.*?)\s+%>     | # <%  inline code or code block %>
+    (<%=)(.*?)%>            # <%= inline code or code block output as string %>
+  /mx
+
+
+  #
+  # Parse and translate the template string into ruby source code.
+  #
+  def transform(template)
+    atoms = template.split(ERB_EVAL_OPERATORS)
+    source = "Proc.new do __o='';"
+
+    while (atom = atoms.shift)
+      case atom
+      when "%" ,"<%"  then source << "#{atoms.shift}\n"
+      when "%=","<%=" then source << "__o << (#{atoms.shift}).to_s\n"
+      else                 source << "__o << #{atom.dump}\n"
+      end
+    end
+
+    source << "__o; end"
+  end
+
+  #
+  # Outputs the contents of the template +filename+.  Erb files are evaluated
+  # in the current context.  All other file types are returned verbatim.
+  # Can be called from content or templates.
+  #
+  # Note: layouts are templates with the following exceptions:
+  #   1. Layouts must be Erb files, unlike other templates which could be HTML.
+  #   2. Layouts must be in the "layouts" directory under +TEMPLATES_DIR+.
+  #   3. Layouts are a final destination; no other templates embed them.
+  #   4. Layouts normally call +page.content+ to get the rendered page.
+  #
+  def template(filename)
+    template_source = File.read(File.join(TEMPLATES_DIR, filename))
+
+    if filename.end_with? '.erb'
+      instance_eval(transform(template_source)).call
+    else
+      template_source
+    end
+  end
+
+  #
+  # Sets an ID cookie using pixel.
+  #
+  def memo
+    "<img src='/memo-#{rand(1E6)}' alt='' loading='eager'>"
+  end
+
+  #
+  # Kramdown table of contents marker.
+  #
+  def toc(auto_ids = true, levels = 2..6)
+    "0. TOC\n{:toc .toc}\n" \
+    "{::options auto_ids='#{auto_ids}' toc_levels='#{levels}' /}"
+  end
+
+  #
+  # Obfuscates +email+ address in a mailto hyperlink using Javascript. The
+  # optional display +text+ defaults to the encoded email address.
+  #
+  def mailto email, text = nil
+    encoded_proto = "0x6d,97,0151,0x6c,116,0157,072" #=> mailto: (hex/dec/oct)
+    encoded_email = email.codepoints.join(',')
+
+    link = "'+String.fromCodePoint(#{encoded_proto},#{encoded_email})+'"
+    text = "'+String.fromCodePoint(#{encoded_email})+'" unless text
+
+    %Q(<script>document.write('<a href="#{link}">#{text}</a>')</script>)
+  end
+
+  #
+  # Manages figure enumeration and references.
+  #
+  # For example, reference a defined figure:
+  #
+  #   <p>This is demonstrated in <%= figure.ref :my_fig_name %>.
+  #   ...
+  #   <figure>
+  #     <img>
+  #     <figcaption><%= figure.name :my_fig_name %></figcaption>
+  #   </figure>
+  #
+  class Figure
+    def initialize
+      @figures = Hash.new {|hsh, name| hsh[name] = hsh.size + 1 }
+      @names = [] # permits name/ref to be called in any order
+    end
+
+    def name figname
+      if @names.include? figname
+        raise "Figure name `#{figname}' already defined."
+      else
+        @names << figname
+      end
+      "<span class='figname'>Figure #{@figures[figname]}.</span>"
+    end
+
+    def ref figname
+      "<span class='figref'>Figure #{@figures[figname]}</span>"
+    end
+  end
+
+  def figure
+    @figure ||= Figure.new
+  end
+
+end

data/xstatic.gemspec

@@ -0,0 +1,37 @@
+Gem::Specification.new('xstatic') do |s|
+  s.version     = '0.1.0'
+  s.author      = 'Clint Pachl'
+  s.email       = 'pachl@ecentryx.com'
+  s.homepage    = 'https://ecentryx.com/gems/xstatic'
+  s.license     = 'ISC'
+  s.summary     = 'Fast, dependency-aware, static site generator'
+  s.description = <<EOS
+A smart, static site generator that automatically manages dependencies to
+achieve blazing build times with minimal cognitive load. Only new and changed
+files, and files upstream of a changed dependency are processed. Renders
+markdown or embedded-Ruby (Erb-like) content as HTML.
+
+Supports templates (embedded & layout), which may be included within content
+sources or other templates. Document metadata may me added using a plain-text
+preamble of key-value pairs. Generates a complete website that can be served by
+the built-in WEBrick server.
+EOS
+  s.executables << 'xstatic'
+  s.add_runtime_dependency 'kramdown', '~> 2.3', '>= 2.3.0'
+  s.rdoc_options = [
+    '--title', "XStatic Ruby Gem: #{s.summary}",
+    '--main', 'README.rdoc'
+  ]
+  s.extra_rdoc_files = Dir[
+    'DESIGN*',
+    'README*',
+    'TODO*',
+    'lib/**/*.rb',
+  ]
+  s.files = Dir[
+    '*.gemspec',
+    'Rakefile',
+    'bin/*',
+    'test/**/*'
+  ] + s.extra_rdoc_files
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: xstatic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Clint Pachl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-01-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+description: |
+  A smart, static site generator that automatically manages dependencies to
+  achieve blazing build times with minimal cognitive load. Only new and changed
+  files, and files upstream of a changed dependency are processed. Renders
+  markdown or embedded-Ruby (Erb-like) content as HTML.
+
+  Supports templates (embedded & layout), which may be included within content
+  sources or other templates. Document metadata may me added using a plain-text
+  preamble of key-value pairs. Generates a complete website that can be served by
+  the built-in WEBrick server.
+email: pachl@ecentryx.com
+executables:
+- xstatic
+extensions: []
+extra_rdoc_files:
+- DESIGN.rdoc
+- README.rdoc
+- TODO
+- lib/html_page.rb
+files:
+- DESIGN.rdoc
+- README.rdoc
+- Rakefile
+- TODO
+- bin/xstatic
+- lib/html_page.rb
+- xstatic.gemspec
+homepage: https://ecentryx.com/gems/xstatic
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--title"
+- 'XStatic Ruby Gem: Fast, dependency-aware, static site generator'
+- "--main"
+- README.rdoc
+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: []
+rubygems_version: 3.2.32
+signing_key: 
+specification_version: 4
+summary: Fast, dependency-aware, static site generator
+test_files: []