foresite 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 495db3b9b94366d4ec2ee21650912ce9f545ccab88a5206aebf49e6cb08cfee8
+  data.tar.gz: 1712e43ee2800c9158fb54879423693b5f764e0f7ad53565ebff9151c76e322d
+SHA512:
+  metadata.gz: 3079e9d70d3d1020d209251caeb1bc85b6a286d9db03bb9a29a8abfaecdbb0522f815b8680ceab129a4247388dfe2d5d8326c275f975c3b1608b83fea18b1f6d
+  data.tar.gz: e5263d34aea71db355288285d168e607fbfe30415bbc19b5eb2679bddbf48ebc255118e58b8c7bfa13ea2f1fbf24bca4e3c5136a4c62e4bbdd7d9e8e71c085fa

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Carl Wiedemann
+
+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,128 @@
+# Foresite
+
+An extremely minimal static site generator.
+
+CLI executable that converts markdown wrapped in a single template to static HTML for simple blogs hosted on [GitHub Pages](https://pages.github.com/) or similar.
+
+## Installation
+
+The only requirement is Ruby >= 2.7.0.
+
+    $ gem install foresite
+
+## Quick start: Hello World
+
+    $ mkdir my_blog                 # Create a project directory
+
+    $ cd my_blog
+
+    $ foresite init                 # Initialize
+
+    $ foresite touch "Hello World"  # Create markdown post titled "Hello World"
+
+    $ foresite build                # Converts markdown to HTML
+
+![Screenshot of Hello World post](screenshot.png)
+
+## Getting started guide
+
+### 1. Create your project directory
+
+Create a project directory for your site and run `foresite init` from within it:
+
+    $ mkdir my_blog
+
+    $ cd my_blog
+
+    $ foresite init
+    Created md/
+    Created post/
+    Created erb/
+    Created erb/post.md.erb
+    Created erb/wrapper.html.erb
+    Created erb/_list.html.erb
+
+Three subdirectories are created, along with three [ERB](https://docs.ruby-lang.org/en/3.2/ERB.html) template files.
+
+Some facts:
+
+* `md` subdirectory will contain markdown files known as posts, which are your site's content.
+* `post` subdirectory will contain HTML files generated from the markdown posts with the exception of an `index.html` file listing all posts, which will exist in the top-level project directory.
+* `erb` subdirectory contains [ERB](https://docs.ruby-lang.org/en/3.2/ERB.html) templates you can modify:
+  * `post.md.erb` is the default markdown file for every post.
+  * `wrapper.html.erb` is a HTML wrapper template for every generated HTML file.
+  * `_list.html.erb` is a HTML template partial for the list of posts on the `index.html` page.
+
+### 2. Write your first post
+
+Run `foresite touch` to generate a new post in the `md` subdirectory. The title is its sole argument.
+
+    $ foresite touch "Welcome to my site"
+    Created md/2023-01-15-welcome-to-my-site.md
+
+    $ cat md/2023-01-15-welcome-to-my-site.md
+    # Welcome to my site
+    
+    2023-01-15
+
+A single markdown file is created in the `md` subdirectory. **This file is meant for you to edit.**
+
+Some facts:
+
+* The title is the first line formatted as H1 (mandatory).
+* Current date in YYYY-MM-DD format is the first markdown paragraph (optional).
+* Current date and title are "slugified" for filename.
+
+### 3. Modify templates as desired
+
+`post.md.erb` is used to when running `foresite touch` for the default markdown content. It has two variables, `@title` for the post title and `@date_ymd` for the created date in ISO 8601 `YYYY-MM-DD` format. Modify to have different defaults when running `foresite touch`.
+
+`wrapper.html.erb` wraps all of your markdown. Its sole variable `@content` will be a given post's HTML (converted from markdown). For the `index.html` file, `@content` will be an list of links to all posts in reverse-chronological order. Modify to have different overall page structure, or to add `<style>` etc.
+
+`_list.html.erb` is used to generate the `<ul>` list of posts on the `index.html` file. Modify to show posts in a different way.
+
+### 4. Generate HTML from markdown
+
+Run `foresite build` to create HTML in the `post` subdirectory and the `index.html` file:
+
+    $ foresite build
+    Created post/2023-01-15-welcome-to-my-site.html
+    Created index.html
+
+In this example, two HTML files are created.
+
+Some facts:
+
+* For every post markdown file in the `md` subdirectory an equivalent HTML file is generated in the `post` subdirectory, each wrapped with wrapper template markup.
+* A single `index.html` file shows a list of links to all posts in reverse-chronological order, prefixed with post date.
+  * Post titles are parsed from the first H1 tag in each post markdown file.
+  * Post dates are parsed from the post markdown filename.
+* Re-running `foresite build` removes and recreates all HTML files in the `post` subdirectory as well as the `index.html` file.
+
+In this example, the `index.html` will contain:
+
+```html
+<ul>
+  <li>2023-01-15 <a href="2023-01-15-welcome-to-my-site.html">Welcome to my site</a></li>
+</ul>
+```
+
+## Development
+
+1. Clone
+2. `bundle` to install dependencies
+3. `bundle exec rake` to run tests & linter
+
+To install this gem from local source, run `bundle exec rake install:local`.
+
+## Contributing
+
+Bug reports and pull requests are welcome. The goals of Foresite are:
+
+* Extremely lightweight
+* Simple to use & understand
+* Minimal features
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/foresite

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require_relative '../lib/foresite'
+Foresite::Cli.start

data/lib/foresite/cli.rb

@@ -0,0 +1,120 @@
+module Foresite
+  ##
+  # Cli class.
+  #
+  # For CLI functionality to generate static content.
+  #
+  class Cli < ::Thor
+    ##
+    # Ensure that failures exit with a status of zero.
+    #
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "init", "Initializes foresite in current directory"
+    long_desc <<-LONGDESC
+      Initializes foresite in the current directory.
+
+      Creates `#{Foresite::DIRNAME_MARKDOWN}/` for storing editable markdown posts, `#{Foresite::DIRNAME_POST}/` for storing generated HTML, and `#{Foresite::DIRNAME_ERB}` for storing editable template.
+
+      Does not overwrite existing subdirectories.
+    LONGDESC
+
+    def init
+      unless Foresite.root_exists?
+        warn("Nonexistent directory #{Foresite.get_path_to_root}")
+        exit(1)
+      end
+
+      unless Foresite.root_writable?
+        warn("Cannot write to directory #{Foresite.get_path_to_root}")
+        exit(1)
+      end
+
+      Foresite.touch_directories.map { $stdout.puts(_1) }
+      Foresite.copy_templates.map { $stdout.puts(_1) }
+    end
+
+    desc "touch [TITLE]", "Creates new `.md` file with TITLE in `#{Foresite::DIRNAME_MARKDOWN}` directory"
+    long_desc <<-LONGDESC
+      Creates a markdown file for usage as a post, with optional title.
+
+      The name of the file will be the current date suffixed by the `TITLE` argument. The current date will be formatted as `YYYY-MM-DD` and the title will be transformed to use lowercase alphanumeric characters, separated by hyphens.
+
+      Example: (If today is 14 January 2023, and the command is run from /Users/carlos/my_project)
+
+      $ foresite touch "Happy new year!"
+      \x5> Created #{Foresite::DIRNAME_MARKDOWN}/2023-01-14-happy-new-year.md
+    LONGDESC
+
+    def touch(title)
+      unless Foresite.subdirectories_exist?
+        warn("Missing subdirectories, try running `foresite init`")
+        exit(1)
+      end
+
+      date_ymd = Time.now.strftime("%F")
+      slug = title.downcase.gsub(/[^a-z]/i, " ").strip.gsub(/ +/, "-")
+
+      path = Foresite.get_path_to_md_file("#{date_ymd}-#{slug}.md")
+
+      if File.exist?(path)
+        $stdout.puts("File #{Foresite.relative_path(path)} already exists")
+      else
+        File.write(path, Foresite.render_post(title, date_ymd))
+        $stdout.puts("Created #{Foresite.relative_path(path)}")
+      end
+    end
+
+    desc "build", "Generates HTML from markdown into `#{Foresite::DIRNAME_POST}` directory"
+    long_desc <<-LONGDESC
+      Creates HTML files from all markdown posts and writes them to the `#{Foresite::DIRNAME_POST}` directory.
+
+      The names of the HTML files match corresponding markdown files with extension `.html` instead of `.md`.
+    LONGDESC
+
+    def build
+      unless Foresite.subdirectories_exist?
+        warn("Missing subdirectories, try running `foresite init`")
+        exit(1)
+      end
+
+      # Wipe all output files.
+      Dir.glob(File.join(Foresite.get_path_to_out, "*.html")).each { File.delete(_1) }
+      File.delete(Foresite.get_path_to_index_file) if File.exist?(Foresite.get_path_to_index_file)
+
+      markdown_paths = Dir.glob(File.join(Foresite.get_path_to_md, "*.md"))
+
+      if markdown_paths.count == 0
+        warn("No markdown files, try running `foresite touch`")
+        exit(1)
+      end
+
+      links = markdown_paths.map do |markdown_path|
+        markdown_content = File.read(markdown_path)
+
+        filename_markdown = File.basename(markdown_path)
+        html_path = Foresite.get_path_to_out_file(filename_markdown.gsub(/\.md$/, ".html"))
+
+        File.write(html_path, Foresite.render_wrapped(markdown_content))
+        $stdout.puts("Created #{Foresite.relative_path(html_path)}")
+
+        # Extract date if it exists.
+        match_data = /\d{4}-\d{2}-\d{2}/.match(filename_markdown)
+
+        {
+          date_ymd: match_data.nil? ? "" : match_data[0],
+          href: Foresite.relative_path(html_path),
+          title: markdown_content.split("\n").first { |line| /^# [a-z]/i =~ line }.gsub(/^#/, "").strip
+        }
+      end
+
+      # Generate index file.
+      index_html_path = Foresite.get_path_to_index_file
+      File.write(index_html_path, Foresite.render_wrapped_index(links))
+
+      $stdout.puts("Created #{Foresite.relative_path(index_html_path)}")
+    end
+  end
+end

data/lib/foresite/renderer.rb

@@ -0,0 +1,43 @@
+module Foresite
+  ##
+  # Renderer class.
+  #
+  # Basic implementation of ERB for a path to a given template and variables.
+  #
+  class Renderer
+    ##
+    # Constructor.
+    #
+    # @param [String] path Path to file.
+    # @param [Hash] vars Variables for template.
+    def initialize(path, vars)
+      @path = path
+      vars.each do |k, v|
+        if k.is_a?(Symbol)
+          instance_variable_set("@#{k}".to_sym, v)
+        end
+      end
+    end
+
+    ##
+    # Renders template with variables.
+    #
+    # @return [String] Rendered template output.
+    #
+    def render
+      ::ERB.new(File.read(@path), trim_mode: "-").result(binding)
+    end
+
+    ##
+    # Statically renders template with variables.
+    #
+    # @param [String] path Path to file.
+    # @param [Hash] vars Variables for template.
+    #
+    # @return [String] Rendered template output.
+    #
+    def self.render(path, vars)
+      new(path, vars).render
+    end
+  end
+end

data/lib/foresite/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Foresite
+  VERSION = "1.1.3"
+end

data/lib/foresite.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "erb"
+require "thor"
+require "kramdown"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Foresite
+  DIRNAME_MARKDOWN = "md"
+  DIRNAME_POST = "post"
+  DIRNAME_ERB = "erb"
+
+  FILENAME_POST_MD = "post.md.erb"
+  FILENAME_WRAPPER_HTML = "wrapper.html.erb"
+  FILENAME_LIST_HTML = "_list.html.erb"
+
+  ENV_ROOT = "FORESITE_ROOT"
+
+  PATH_TO_DEFAULTS = File.join(__dir__, "skeleton")
+
+  def self.get_path_to_root
+    ENV[ENV_ROOT] || Dir.pwd
+  end
+
+  def self.root_exists?
+    Dir.exist?(get_path_to_root)
+  end
+
+  def self.root_writable?
+    File.writable?(get_path_to_root)
+  end
+
+  def self.subdirectories_exist?
+    [get_path_to_md, get_path_to_out, get_path_to_erb].all? do |path|
+      Dir.exist?(path)
+    end
+  end
+
+  def self.get_path_to_md
+    File.join(get_path_to_root, DIRNAME_MARKDOWN)
+  end
+
+  def self.get_path_to_out
+    File.join(get_path_to_root, DIRNAME_POST)
+  end
+
+  def self.get_path_to_erb
+    File.join(get_path_to_root, DIRNAME_ERB)
+  end
+
+  def self.get_path_to_erb_file(file)
+    File.join(get_path_to_erb, file)
+  end
+
+  def self.get_path_to_md_file(file)
+    File.join(get_path_to_md, file)
+  end
+
+  def self.get_path_to_out_file(file)
+    File.join(get_path_to_out, file)
+  end
+
+  def self.get_path_to_index_file
+    File.join(get_path_to_root, "index.html")
+  end
+
+  def self.relative_path(full_path)
+    full_path.gsub(get_path_to_root, "").gsub(Regexp.new("^#{File::SEPARATOR}"), "")
+  end
+
+  def self.render_erb_file(file, vars)
+    Renderer.render(get_path_to_erb_file(file), vars)
+  end
+
+  def self.render_post(title, date_ymd)
+    render_erb_file(FILENAME_POST_MD, {
+      title: title,
+      date_ymd: date_ymd
+    })
+  end
+
+  def self.render_wrapped(markdown_content)
+    render_erb_file(FILENAME_WRAPPER_HTML, {
+      content: ::Kramdown::Document.new(markdown_content).to_html
+    })
+  end
+
+  def self.render_wrapped_index(links)
+    render_erb_file(FILENAME_WRAPPER_HTML, {
+      content: render_erb_file(FILENAME_LIST_HTML, {
+        links: links.reverse
+      })
+    })
+  end
+
+  def self.touch_directories
+    [get_path_to_md, get_path_to_out, get_path_to_erb].map do |path|
+      if Dir.exist?(path)
+        "#{relative_path(path)}/ already exists"
+      else
+        Dir.mkdir(path)
+        "Created #{relative_path(path)}/"
+      end
+    end
+  end
+
+  def self.copy_templates
+    [FILENAME_POST_MD, FILENAME_WRAPPER_HTML, FILENAME_LIST_HTML].map do |filename|
+      full_file_path = File.join(get_path_to_erb, filename)
+      if File.exist?(full_file_path)
+        "#{relative_path(full_file_path)} already exists"
+      else
+        File.copy_stream(File.join(PATH_TO_DEFAULTS, filename), full_file_path)
+        "Created #{relative_path(full_file_path)}"
+      end
+    end
+  end
+end

data/lib/skeleton/_list.html.erb

@@ -0,0 +1,7 @@
+<% if @links.count > 0 -%>
+<ul>
+<% @links.each do |link| -%>
+  <li><%= link[:date_ymd] %> <a href="<%= link[:href] %>"><%= link[:title] %></a></li>
+<% end -%>
+</ul>
+<% end -%>

data/lib/skeleton/post.md.erb

@@ -0,0 +1,4 @@
+# <%= @title %>
+
+<%= @date_ymd %>
+

data/lib/skeleton/wrapper.html.erb

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Another Foresite Blog</title>
+  <style></style>
+</head>
+<body>
+<header>
+  <h1><a href="/">Another Foresite Blog</a></h1>
+  <nav>
+    <ul>
+      <li><a href="https://rubygems.org/gems/foresite">Foresite on RubyGems</a></li>
+      <li><a href="https://github.com/carlwiedemann/foresite">Foresite on GitHub</a></li>
+    </ul>
+  </nav>
+</header>
+<main>
+<%= @content %>
+</main>
+<footer></footer>
+</body>
+</html>

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: foresite
+version: !ruby/object:Gem::Version
+  version: 1.1.3
+platform: ruby
+authors:
+- Carl Wiedemann
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description:
+email:
+- carl.wiedemann@gmail.com
+executables:
+- foresite
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- bin/foresite
+- lib/foresite.rb
+- lib/foresite/cli.rb
+- lib/foresite/renderer.rb
+- lib/foresite/version.rb
+- lib/skeleton/_list.html.erb
+- lib/skeleton/post.md.erb
+- lib/skeleton/wrapper.html.erb
+homepage: https://github.com/carlwiedemann/foresite
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/carlwiedemann/foresite
+  source_code_uri: https://github.com/carlwiedemann/foresite
+  changelog_uri: https://github.com/carlwiedemann/foresite/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.3
+signing_key:
+specification_version: 4
+summary: An extremely minimal static site generator.
+test_files: []