ruby-md-ssg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df65115f64a772c620d615e8b0bb752d340bc47821ffc9228a976369c8a65514
+  data.tar.gz: 1b0e4cfd186cb5b26c0d61051579ab13aec4b0ddf2afe7ec42f5d02d593e364f
+SHA512:
+  metadata.gz: 283a2e7203583828fd569f7104b87f8b60a14991562070b315e6b057156fc0fe6015aa10eef6b6d4d371c25b626ef2ab2da943e3153bfff2c63852fc47e34a5e
+  data.tar.gz: f8fdc454c0b484223430bcc130e230fff533f472a8306230d9fe467b4d258ae98b7c86b6c3ecc8b1fd4b4a4ff6e2dcc511259643982fb9a4c30047157ca11b3d

data/AGENTS.md

@@ -0,0 +1,17 @@
+# Maintainer Guide
+
+## Project Structure
+Core code lives under `lib/ruby_md_ssg/` (compiler, CLI, server, helpers). Executables are in `exe/`, and the site scaffold lives in `template/site/`. Tests reside in `test/` and mirror the public API. The gem spec is `ruby-md-ssg.gemspec`.
+
+## Development Commands
+Run `bundle install` after touching the gemspec. Use `bundle exec ruby bin/test` (wrapper around the Minitest suite) before publishing. `bundle exec ruby_md_ssg build` from a test project exercises the full pipeline and should emit `sitemap.xml`; set `RUBY_MD_SSG_BASE_URL` (or pass `--base-url`) to control sitemap URLs.
+
+CI lives in `.github/workflows/test.yml` (runs RuboCop, then the test suite on pushes/PRs). Publishing is handled by `.github/workflows/release.yml`; configure the repository secret `RUBYGEMS_API_KEY` before dispatching the workflow or pushing a `v*` tag.
+
+## Releasing
+1. Update `lib/ruby_md_ssg/version.rb`.
+2. Run `bundle exec rake release` (after configuring credentials).
+3. Update downstream projects (e.g., `ruby-md-ssg-example`) to the new version.
+
+## Context Logging
+See `CONTEXT_LOG.md` for recent architectural changes.

data/CONTEXT_LOG.md

@@ -0,0 +1,6 @@
+## 2024-10-08
+- Extracted gem from the original project: contains library code, CLI, scaffold template, and test suite.
+- Added helper-backed ERB templates for scaffolding and ensured tests cover project generation.
+- Added GitHub Actions workflows for CI (`.github/workflows/test.yml`) and RubyGems publishing (`.github/workflows/release.yml`).
+- Renamed gem to `ruby-md-ssg`, updated namespaces/commands, and refreshed documentation and tests to reflect the new branding.
+- Compiler now emits `sitemap.xml` (with optional `--base-url` support), CI runs RuboCop before executing tests, and the scaffold ships a GitHub Pages deploy workflow.

data/README.md

@@ -0,0 +1,17 @@
+# Ruby MD SSG
+
+The `ruby-md-ssg` gem exposes a command-line interface for building and serving markdown-driven static sites.
+
+## Development
+
+```bash
+bundle install
+bundle exec ruby bin/test
+```
+
+## CLI
+
+- `ruby_md_ssg new my-site` — scaffold a new project using the bundled template
+- `ruby_md_ssg build` — regenerate the site into `build/` (also emits `sitemap.xml`; pass `--base-url` to control absolute URLs)
+- `ruby_md_ssg serve` — serve the site locally with automatic rebuilds
+- `ruby_md_ssg menu` — refresh `docs/menu.yml`

data/exe/ruby_md_ssg

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib_path = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_path) if Dir.exist?(lib_path)
+
+require 'ruby_md_ssg'
+
+RubyMdSsg::CLI.start(ARGV)

data/lib/ruby_md_ssg/cli.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'fileutils'
+require 'erb'
+
+module RubyMdSsg
+  class CLI
+    BINDING_STRUCT = Struct.new(
+      :project_name,
+      :module_name,
+      :gem_version,
+      :helpers,
+      keyword_init: true
+    ) do
+      def to_binding
+        binding
+      end
+    end
+    private_constant :BINDING_STRUCT
+
+    TEMPLATE_DIR = File.expand_path('../../template/site', __dir__)
+
+    def self.start(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      command = argv.shift
+      case command
+      when 'new'
+        handle_new(argv)
+      when 'build'
+        handle_build(argv)
+      when 'serve'
+        handle_serve(argv)
+      when 'menu'
+        handle_menu(argv)
+      when 'version', '--version', '-v'
+        puts "Ruby MD SSG #{RubyMdSsg::VERSION}"
+      else
+        puts usage
+        command ? exit(1) : exit(0)
+      end
+    end
+
+    private
+
+    attr_reader :argv
+
+    def usage
+      <<~TEXT
+        Usage: ruby_md_ssg <command> [options]
+
+        Commands:
+          new NAME           # Scaffold a new Ruby MD SSG project
+          build              # Generate the site into the build directory (writes sitemap.xml)
+          serve              # Serve the site locally with rebuilds
+          menu               # Regenerate docs/menu.yml from docs/
+          version            # Show gem version
+      TEXT
+    end
+
+    def handle_new(args)
+      options = { path: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: ruby_md_ssg new NAME [options]'
+        opts.on('-pPATH', '--path=PATH', 'Target directory (defaults to NAME)') do |path|
+          options[:path] = File.expand_path(path)
+        end
+      end
+      parser.parse!(args)
+
+      project_name = args.shift
+      unless project_name
+        warn 'Project name is required.'
+        puts parser
+        exit 1
+      end
+
+      destination = options[:path] || File.expand_path(project_name)
+      Scaffold.new(project_name, destination).run
+      puts "Created Ruby MD SSG project at #{destination}"
+    end
+
+    def handle_build(args)
+      RubyMdSsg::Paths.reset!
+      RubyMdSsg::Paths.root = Dir.pwd
+      options = build_options(args)
+
+      generator = RubyMdSsg::MenuGenerator.new(docs_dir: options[:docs], menu_path: options[:menu])
+      generator.generate
+
+      compiler = RubyMdSsg::Compiler.new(
+        docs_dir: options[:docs],
+        build_dir: options[:build],
+        assets_dir: options[:assets],
+        menu_path: options[:menu],
+        base_url: options[:base_url]
+      )
+      compiler.compile
+    end
+
+    def handle_menu(args)
+      RubyMdSsg::Paths.reset!
+      RubyMdSsg::Paths.root = Dir.pwd
+      options = build_options(args)
+      generator = RubyMdSsg::MenuGenerator.new(docs_dir: options[:docs], menu_path: options[:menu])
+      generator.generate
+    end
+
+    def handle_serve(args)
+      RubyMdSsg::Paths.reset!
+      RubyMdSsg::Paths.root = Dir.pwd
+      options = build_options(args)
+      RubyMdSsg::Server.start(options)
+    end
+
+    def build_options(args)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Options:'
+        opts.on('--docs PATH', 'Directory containing markdown docs') do |path|
+          options[:docs] = File.expand_path(path)
+        end
+        opts.on('--build PATH', 'Build output directory') do |path|
+          options[:build] = File.expand_path(path)
+        end
+        opts.on('--menu PATH', 'Menu configuration path') do |path|
+          options[:menu] = File.expand_path(path)
+        end
+        opts.on('--assets PATH', 'Assets directory') do |path|
+          options[:assets] = File.expand_path(path)
+        end
+        opts.on(
+          '--base-url URL',
+          'Base URL for sitemap entries (defaults to ENV RUBY_MD_SSG_BASE_URL)'
+        ) do |url|
+          options[:base_url] = url
+        end
+        opts.on('--port PORT', Integer, 'Port for serve command (default: 4000)') do |port|
+          options[:port] = port
+        end
+        opts.on('--[no-]auto-build', 'Serve only: build before starting (default: true)') do |flag|
+          options[:auto_build] = flag
+        end
+        opts.on('--[no-]watch', 'Serve only: watch for changes (default: true)') do |flag|
+          options[:watch] = flag
+        end
+        opts.on(
+          '--interval SECONDS', Float,
+          'Serve only: watch interval (default: 1.0)'
+        ) do |seconds|
+          options[:interval] = seconds
+        end
+      end
+      parser.parse!(args)
+
+      options[:docs] ||= RubyMdSsg::Paths.docs_dir
+      options[:build] ||= RubyMdSsg::Paths.build_dir
+      options[:menu] ||= RubyMdSsg::Paths.menu_config
+      options[:assets] ||= RubyMdSsg::Paths.assets_dir
+      options[:base_url] ||= ENV.fetch('RUBY_MD_SSG_BASE_URL', nil)
+      options.delete_if { |_key, value| value.nil? }
+    end
+
+    class Scaffold
+      attr_reader :project_name, :destination
+
+      def initialize(project_name, destination)
+        @project_name = project_name
+        @destination = destination
+      end
+
+      def run
+        raise "Directory already exists: #{destination}" if File.exist?(destination)
+
+        FileUtils.mkdir_p(destination)
+        copy_template
+        post_process
+      end
+
+      private
+
+      def copy_template
+        Dir.glob(File.join(TEMPLATE_DIR, '**', '*'), File::FNM_DOTMATCH).each do |source|
+          next if ['.', '..'].include?(File.basename(source))
+
+          relative = source.delete_prefix("#{TEMPLATE_DIR}/")
+          templated = source.end_with?('.erb') && !relative.start_with?('templates/')
+          target_relative = templated ? relative.sub(/\.erb\z/, '') : relative
+          target = File.join(destination, target_relative)
+
+          if File.directory?(source)
+            FileUtils.mkdir_p(target)
+          else
+            content = if templated
+                        ERB.new(File.read(source), trim_mode: '-').result(binding_context)
+                      else
+                        File.binread(source)
+                      end
+            FileUtils.mkdir_p(File.dirname(target))
+            File.write(target, content)
+            File.chmod(File.stat(source).mode & 0o777, target)
+          end
+        end
+      end
+
+      def post_process
+        FileUtils.mkdir_p(File.join(destination, 'build'))
+      end
+
+      def binding_context
+        BINDING_STRUCT.new(
+          project_name: project_name,
+          module_name: module_name,
+          gem_version: RubyMdSsg::VERSION,
+          helpers: HelperMethods.new(project_name)
+        ).to_binding
+      end
+
+      def module_name
+        normalize_identifier(project_name)
+      end
+
+      def normalize_identifier(value)
+        value.split(/[^a-zA-Z0-9]/).reject(&:empty?).map(&:capitalize).join
+      end
+
+      class HelperMethods
+        def initialize(project_name)
+          @project_name = project_name
+        end
+
+        def human_project_name
+          @human_project_name ||= begin
+            parts = @project_name
+                    .split(/[^a-zA-Z0-9]/)
+                    .reject(&:empty?)
+                    .map(&:capitalize)
+            parts.join(' ')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_md_ssg/compiler.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'nokogiri'
+require_relative 'paths'
+require_relative 'document_finder'
+require_relative 'menu_config'
+require_relative 'markdown_renderer'
+require_relative 'layout_renderer'
+require_relative 'html_formatter'
+
+module RubyMdSsg
+  class Compiler
+    def initialize(
+      docs_dir: Paths.docs_dir,
+      build_dir: Paths.build_dir,
+      assets_dir: Paths.assets_dir,
+      menu_path: Paths.menu_config,
+      base_url: nil
+    )
+      @docs_dir = docs_dir
+      @build_dir = build_dir
+      @assets_dir = assets_dir
+      @menu_path = menu_path
+      @base_url = base_url
+      @markdown = MarkdownRenderer.new
+      @layout = LayoutRenderer.new
+      @html_formatter = HtmlFormatter.new
+    end
+
+    def compile
+      purge_build
+      ensure_build_structure
+
+      documents = DocumentFinder.new(docs_dir: docs_dir).all
+      menu = menu_from_configuration(documents)
+
+      documents.each do |document|
+        render_document(document, menu)
+      end
+
+      copy_assets
+      generate_sitemap(documents)
+    end
+
+    private
+
+    attr_reader :docs_dir, :build_dir, :assets_dir, :menu_path,
+                :markdown, :layout, :html_formatter, :base_url
+
+    def purge_build
+      FileUtils.rm_rf(build_dir)
+    end
+
+    def ensure_build_structure
+      FileUtils.mkdir_p(build_dir)
+      FileUtils.mkdir_p(File.join(build_dir, 'assets'))
+    end
+
+    def menu_from_configuration(documents)
+      if File.exist?(menu_path)
+        MenuConfig.load(menu_path)
+      else
+        MenuConfig.from_documents(documents)
+      end
+    end
+
+    def render_document(document, menu)
+      html_body = markdown.render(document.body_markdown)
+      page = layout.render(document: document, body_html: html_body, menu: menu)
+      page = html_formatter.format(page)
+      output_path = document.output_path
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, page)
+    end
+
+    def copy_assets
+      copy_asset('style.css')
+      copy_asset('app.js')
+    end
+
+    def copy_asset(filename)
+      source = File.join(assets_dir, filename)
+      return unless File.exist?(source)
+
+      destination = File.join(build_dir, 'assets', filename)
+      FileUtils.cp(source, destination)
+    end
+
+    def generate_sitemap(documents)
+      return if documents.empty?
+
+      builder = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+        xml.urlset('xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9') do
+          documents.each do |document|
+            xml.url do
+              xml.loc sitemap_location_for(document.route)
+              xml.lastmod(document.last_modified.utc.iso8601)
+            end
+          end
+        end
+      end
+
+      File.write(File.join(build_dir, 'sitemap.xml'), builder.to_xml)
+    end
+
+    def sitemap_location_for(route)
+      normalized_route = route == '/' ? '/' : route
+      return normalized_route if base_url.nil? || base_url.empty?
+
+      normalized_base = base_url.end_with?('/') ? base_url.chomp('/') : base_url
+      normalized_base + normalized_route
+    end
+  end
+end

data/lib/ruby_md_ssg/document.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'paths'
+
+module RubyMdSsg
+  # Represents a markdown document and its derived site metadata.
+  class Document
+    attr_reader :source_path, :docs_dir
+
+    def initialize(source_path, docs_dir: Paths.docs_dir)
+      @source_path = source_path
+      @docs_dir = docs_dir
+    end
+
+    def relative_path
+      @relative_path ||= begin
+        prefix = "#{docs_dir}/"
+        if source_path.start_with?(prefix)
+          source_path.delete_prefix(prefix)
+        else
+          source_path
+        end
+      end
+    end
+
+    def route
+      return '/' if relative_path == 'index.md'
+
+      "/#{relative_path.sub(/\.md\z/, '')}"
+    end
+
+    def output_dir
+      File.join(Paths.build_dir, route.delete_prefix('/'))
+    end
+
+    def output_path
+      if route == '/'
+        File.join(Paths.build_dir, 'index.html')
+      else
+        File.join(output_dir, 'index.html')
+      end
+    end
+
+    def title
+      @title ||= title_from_frontmatter || title_from_heading || default_title
+    end
+
+    def content
+      @content ||= File.read(source_path)
+    end
+
+    def last_modified
+      File.mtime(source_path)
+    end
+
+    def meta_description
+      @meta_description ||= begin
+        value = frontmatter['description'] || frontmatter['meta_description']
+        value&.to_s&.strip
+      end
+    end
+
+    def body_markdown
+      frontmatter_match = content.match(/\A---\s*\n(.*?)\n---\s*\n/m)
+      return content unless frontmatter_match
+
+      content.sub(frontmatter_match[0], '')
+    end
+
+    def frontmatter
+      return @frontmatter if defined?(@frontmatter)
+
+      match = content.match(/\A---\s*\n(.*?)\n---\s*\n/m)
+      @frontmatter = if match
+                       YAML.safe_load(match[1]) || {}
+                     else
+                       {}
+                     end
+    end
+
+    private
+
+    def title_from_frontmatter
+      frontmatter['title']
+    end
+
+    def title_from_heading
+      line = content.each_line.find { |l| l.start_with?('# ') }
+      return unless line
+
+      heading = line.split('# ', 2).last
+      heading&.strip
+    end
+
+    def default_title
+      File.basename(relative_path, '.md').tr('_-', ' ').split.map(&:capitalize).join(' ')
+    end
+  end
+end

data/lib/ruby_md_ssg/document_finder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'paths'
+require_relative 'document'
+
+module RubyMdSsg
+  class DocumentFinder
+    def initialize(docs_dir: Paths.docs_dir)
+      @docs_dir = docs_dir
+    end
+
+    def all
+      markdown_files.map { |path| Document.new(path, docs_dir: docs_dir) }
+    end
+
+    private
+
+    attr_reader :docs_dir
+
+    def markdown_files
+      Dir.glob(File.join(docs_dir, '**', '*.md'), sort: true)
+    end
+  end
+end

data/lib/ruby_md_ssg/html_formatter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module RubyMdSsg
+  class HtmlFormatter
+    def initialize(indent: 2)
+      @indent = indent
+    end
+
+    def format(html)
+      document = Nokogiri::HTML5.parse(html)
+      document.to_html(indent: indent)
+    end
+
+    private
+
+    attr_reader :indent
+  end
+end

data/lib/ruby_md_ssg/layout_renderer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'erb'
+require_relative 'paths'
+
+module RubyMdSsg
+  class LayoutRenderer
+    def initialize(template_path: default_template_path)
+      @template_path = template_path
+    end
+
+    def render(document:, body_html:, menu:)
+      template.result_with_hash(
+        title: document.title,
+        body_html: body_html,
+        menu: menu,
+        meta_description: document.meta_description
+      )
+    end
+
+    private
+
+    attr_reader :template_path
+
+    def template
+      @template ||= ERB.new(File.read(template_path))
+    end
+
+    def default_template_path
+      File.join(Paths.root, 'templates', 'layout.html.erb')
+    end
+  end
+end

data/lib/ruby_md_ssg/markdown_renderer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'kramdown'
+
+module RubyMdSsg
+  class MarkdownRenderer
+    def render(markdown)
+      Kramdown::Document.new(markdown).to_html
+    end
+  end
+end

data/lib/ruby_md_ssg/menu_config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'paths'
+
+module RubyMdSsg
+  class MenuConfig
+    Section = Struct.new(:title, :links, keyword_init: true)
+    Link = Struct.new(:label, :route, keyword_init: true)
+
+    def self.load(path = Paths.menu_config)
+      return new([]) unless File.exist?(path)
+
+      raw = YAML.safe_load_file(path) || {}
+      sections = Array(raw['sections']).map do |section|
+        Section.new(
+          title: section['title'],
+          links: Array(section['links']).map do |link|
+            Link.new(label: link['label'], route: link['route'])
+          end
+        )
+      end
+      new(sections)
+    end
+
+    def self.from_documents(documents)
+      grouped = documents.group_by { |doc| top_level_segment(doc.route) }
+      sections = grouped.keys.sort.map do |segment|
+        docs_in_group = grouped[segment]
+        Section.new(
+          title: segment_title(segment),
+          links: docs_in_group.sort_by(&:route).map do |doc|
+            Link.new(label: doc.title, route: doc.route)
+          end
+        )
+      end
+      new(sections)
+    end
+
+    def initialize(sections)
+      @sections = sections
+    end
+
+    attr_reader :sections
+
+    def to_h
+      {
+        'sections' => sections.map do |section|
+          {
+            'title' => section.title,
+            'links' => section.links.map do |link|
+              { 'label' => link.label, 'route' => link.route }
+            end
+          }
+        end
+      }
+    end
+
+    private_class_method def self.top_level_segment(route)
+      return 'home' if route == '/'
+
+      route.split('/')[1]
+    end
+
+    private_class_method def self.segment_title(segment)
+      return 'Home' if segment == 'home'
+
+      segment.to_s.tr('_-', ' ').split.map(&:capitalize).join(' ')
+    end
+  end
+end