indexmap 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef452a5928b87f84f65ecb9ba2afcab5340d9d09c5d8c8dfd8c4ffb3217a68fd
-  data.tar.gz: 03b11e1d9360bbd797d6b61886c99d1619247877dfd2c4676efeca9a1119764c
+  metadata.gz: 64a9d1c671519fea6ba6a46b7f67daed2784ad5aaccf2594dc3aa0a374f55854
+  data.tar.gz: 50f6bc13a8097194dec9736b96c8cc6baf0f76429edf0175372aee97991c63f0
 SHA512:
-  metadata.gz: a04a772029e2438636df90b65004a27c54e1cf3360205fd556feff615768fd527668fe2a3e3063f2831b9af9afb4edd983e48e73b922278c4c10a63d936b938e
-  data.tar.gz: 6ce68d9ee6343aaf7c4bbff6860a712d743899390b4a8a3a09c712694c95cff32cc0acd85f30a43e2ba37f0c8ff671d2af11028e63976649ae90e5100d5e0a1b
+  metadata.gz: 2ce92a1da076303265c03ff833585b069215c8417b134407850770c64ae04b3ab93fcf894484874e710e304c6b3c94f19247d70073aaa6ba5e170f70212e4992
+  data.tar.gz: 991f39cd9db707dd79e7a404e636aaea8c8a1db07ce5b59d2daf9d73c33a55d39c252d6edef2adf8fc98ea22e153f8619aee4f67f9fd11c3fccf56b473bb1ffa

data/CHANGELOG.md

@@ -5,14 +5,124 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.1] - 2026-05-31
+
+
+### Documentation
+
+- document google search console credentials
+
+
+
+
+### Fixed
+
+- preserve release changelog history ([#13](https://github.com/ethos-link/indexmap/pull/13))
+
+- improve sitemap create output ([#14](https://github.com/ethos-link/indexmap/pull/14))
+
+
+
+## [0.7.0] - 2026-05-08
+
+
+### Fixed
+
+- avoid rewriting existing IndexNow key files ([#11](https://github.com/ethos-link/indexmap/pull/11))
+
+
+
 ## [0.6.0] - 2026-05-01
 
 
 ### Added
 
-- add the url count to google ping output (#9)
+- add the url count to google ping output ([#9](https://github.com/ethos-link/indexmap/pull/9))
+
+- support named sitemap outputs ([#10](https://github.com/ethos-link/indexmap/pull/10))
+
+
+
+## [0.5.0] - 2026-04-24
+
+
+### Fixed
+
+- namespace rake tasks and harden sitemap validation ([#8](https://github.com/ethos-link/indexmap/pull/8))
+
+
+
+## [0.4.2] - 2026-04-23
+
+
+### Fixed
+
+- harden sitemap pinging and indexnow key handling ([#7](https://github.com/ethos-link/indexmap/pull/7))
+
+
+
+## [0.4.1] - 2026-04-22
+
+
+### Added
+
+- add output to ping tasks ([#6](https://github.com/ethos-link/indexmap/pull/6))
+
+
+
+## [0.4.0] - 2026-04-22
+
+
+### Documentation
+
+- improve the task messages ([#4](https://github.com/ethos-link/indexmap/pull/4))
+
+
+
+## [0.3.1] - 2026-04-22
+
+
+### Fixed
+
+- fix changelog generation ([#2](https://github.com/ethos-link/indexmap/pull/2))
+
+- harden indexmap runtime defaults and test coverage ([#3](https://github.com/ethos-link/indexmap/pull/3))
+
+
+
+## [0.3.0] - 2026-04-22
+
+
+### Added
+
+- expand indexmap with sitemap parsing, validation, and search engine pinging
+
+
+
+## [0.2.1] - 2026-04-21
+
+
+### Fixed
+
+- publish built gem in release workflow
+
+
+
+## [0.2.0] - 2026-04-21
+
+
+### Added
+
+- add single-file sitemap mode
+
+
+
+## [0.1.0] - 2026-04-21
+
+
+### Added
 
-- support named sitemap outputs (#10)
+- bootstrap indexmap gem
 
 
 

data/README.md

@@ -34,6 +34,17 @@ Or install it directly:
 gem install indexmap
 ```
 
+Upgrading an existing app? Read [UPGRADE.md](UPGRADE.md) before deploying,
+especially if the app uses custom storage or stores sitemap files under a
+directory prefix such as `sitemaps/`.
+
+## Documentation
+
+- [Search engine ping](docs/search-engine-ping.md): Google Search Console
+  credentials, Google property configuration, and IndexNow key setup.
+- [UPGRADE.md](UPGRADE.md): host-app migration steps for public contract
+  changes.
+
 ## Ruby Usage
 
 ```ruby
@@ -51,7 +62,6 @@ sections = [
 
 Indexmap::Writer.new(
   sections: sections,
-  public_path: Pathname("public"),
   base_url: "https://example.com"
 ).write
 ```
@@ -63,7 +73,12 @@ In an initializer:
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.public_path }
+  config.storage = -> do
+    Indexmap::Storage::Filesystem.new(
+      path: Rails.public_path,
+      public_url: config.base_url
+    )
+  end
   config.sections = -> do
     [
       Indexmap::Section.new(
@@ -85,26 +100,26 @@ bin/rails indexmap:sitemap:format
 bin/rails indexmap:sitemap:validate
 ```
 
-`indexmap:sitemap:create` is the main task. It writes sitemap files to a local
-temporary directory, formats them, validates the result, then replaces the final
-XML files. Existing sitemap files are left untouched if generation or validation
-fails.
+`indexmap:sitemap:create` is the main task. It builds sitemap files in memory,
+formats them, validates the result, then writes the final XML files to the
+configured storage. Existing sitemap files are left untouched if generation or
+validation fails.
 
 ### Default Index Mode
 
 This is the default behavior. `indexmap` writes:
 
-- `public/sitemap.xml` as a sitemap index
+- `sitemap.xml` as a sitemap index
 - one or more child sitemap files from `config.sections`
 
 ### Single-File Mode
 
-For sites that only want one `public/sitemap.xml` file:
+For sites that only want one `sitemap.xml` file:
 
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.public_path }
+  config.storage = -> { Indexmap::Storage::Filesystem.new(path: Rails.public_path, public_url: config.base_url) }
   config.format = :single_file
   config.entries = -> do
     [
@@ -122,13 +137,12 @@ In `:single_file` mode, `indexmap` writes a `urlset` directly to `sitemap.xml` a
 Most apps only need the default output. Use named outputs when one part of the
 sitemap must be generated separately, for example when static pages can be
 generated during deploy but database-heavy pages should refresh later. Named
-outputs still write normal sitemap XML files to a filesystem path; storage and
-serving are application concerns.
+outputs write through the same configured storage as the default output.
 
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.root.join("storage/sitemaps") }
+  config.storage = -> { Indexmap::Storage::Filesystem.new(path: Rails.root.join("storage/sitemaps"), public_url: config.base_url) }
   config.sections = -> { Sitemap.sections }
 
   config.output :insights_data do |output|
@@ -151,12 +165,57 @@ Generate only the named output:
 Indexmap.create(:insights_data)
 ```
 
-Named outputs inherit `base_url`, `public_path`, and `format` from the main
-configuration unless you override them.
+Named outputs inherit `base_url` and `format` from the main configuration unless
+you override them. Storage is configured once and shared by every output.
+
+`Indexmap.create` uses the same safe publish flow as the rake task: build,
+format, validate, and then write the final XML file or files to storage.
+
+### Storage
+
+Every `indexmap` operation reads and writes through `config.storage`. The storage
+object is the source of truth for generation, validation, parsing, Google
+submission, IndexNow submission, and IndexNow verification files.
+
+The filesystem adapter stores files in a directory and exposes public URLs from
+the same filenames:
+
+```ruby
+Indexmap.configure do |config|
+  config.base_url = "https://example.com"
+  config.storage = Indexmap::Storage::Filesystem.new(
+    path: Rails.public_path,
+    public_url: "https://example.com"
+  )
+end
+```
+
+Rails apps that store sitemap files in Active Storage can use the optional
+adapter. `indexmap` does not depend on `activestorage`; this adapter only uses
+the model and attachment object you pass in.
+
+```ruby
+Indexmap.configure do |config|
+  config.base_url = "https://example.com"
+  config.storage = Indexmap::Storage::ActiveStorage.new(
+    model: SitemapArtifact,
+    filename_column: :filename,
+    attachment: :file,
+    public_url: "https://example.com"
+  )
+end
+```
+
+Custom storage backends can implement the same small interface:
 
-`Indexmap.create` uses the same safe local publish flow as the rake task:
-generate in a temporary directory, format, validate, and then replace the final
-XML file or files.
+```ruby
+storage.write(filename, body, content_type:)
+storage.read(filename)
+storage.exist?(filename)
+storage.list(prefix:, suffix:)
+storage.delete(filename)
+storage.public_url(filename)
+```
 
 ### Deferred Dynamic Sections
 
@@ -168,7 +227,7 @@ replaced successfully.
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.root.join("storage/sitemaps") }
+  config.storage = -> { Indexmap::Storage::Filesystem.new(path: Rails.root.join("storage/sitemaps"), public_url: config.base_url) }
   config.sections = -> { Sitemap.sections }
 
   config.output :insights_data do |output|
@@ -201,7 +260,7 @@ while database-dependent output is refreshed by the job backend.
 `indexmap` also includes small utilities for working with generated sitemap files:
 
 ```ruby
-parser = Indexmap::Parser.new(path: Rails.public_path.join("sitemap.xml"))
+parser = Indexmap::Parser.new(source: "sitemap.xml")
 parser.paths
 # => ["/", "/about", "/articles/example"]
 
@@ -224,6 +283,8 @@ The built-in validator checks for:
 ## Search Engine Ping
 
 `indexmap` can ping Google Search Console and IndexNow after sitemap generation.
+See [Search engine ping](docs/search-engine-ping.md) for Google credential
+setup, Search Console property configuration, and IndexNow key provisioning.
 
 Available rake tasks:
 
@@ -235,59 +296,9 @@ bin/rails indexmap:index_now:write_key
 bin/rails indexmap:ping
 ```
 
-### Google Search Console
-
-Google pinging requires service account credentials:
-
-```ruby
-Indexmap.configure do |config|
-  config.google.credentials = -> { ENV["GOOGLE_SITEMAP"] }
-end
-```
-
-If `config.google.credentials` is blank, `indexmap:google:ping` skips Google submission.
-
-You can optionally override the Search Console property identifier:
-
-```ruby
-Indexmap.configure do |config|
-  config.google.credentials = -> { ENV["GOOGLE_SITEMAP"] }
-  config.google.property = -> { "sc-domain:example.com" }
-end
-```
-
-If `config.google.property` is not set, `indexmap` defaults to `sc-domain:<host>`.
-
-### IndexNow
-
-IndexNow submission requires a key. `indexmap` supports two ways to provide it:
-
-- set `config.index_now.key`
-- or keep a valid verification file at `public/<key>.txt`
-
-Configured-key example:
-
-```ruby
-Indexmap.configure do |config|
-  config.index_now.key = -> { ENV["INDEXNOW_KEY"] }
-end
-```
-
-If `config.index_now.key` is set, `indexmap:sitemap:create` also writes the matching `public/<key>.txt` verification file automatically.
-
-If you prefer the file-based flow, run:
-
-```bash
-bin/rails indexmap:index_now:write_key
-```
-
-That task:
-
-- reuses an existing valid key file when present
-- otherwise generates a new key in `public/<key>.txt`
-- makes that key available to `indexmap:index_now:ping` without adding `config.index_now.key`
-
-If neither a configured key nor a valid key file is present, `indexmap:index_now:ping` skips IndexNow submission.
+If Google credentials are blank, `indexmap:google:ping` skips Google
+submission. If neither a configured IndexNow key nor a valid key file is
+present, `indexmap:index_now:ping` skips IndexNow submission.
 
 ## Development
 
@@ -315,7 +326,12 @@ Note: `Gemfile.lock` is intentionally not tracked for this gem, following normal
 
 ### Git hooks
 
-We use [lefthook](https://lefthook.dev/) with the Ruby [commitlint](https://github.com/arandilopez/commitlint) gem to enforce Conventional Commits on every commit. We also use [Standard Ruby](https://standardrb.com/) to keep code style consistent. CI validates commit messages, Standard Ruby, tests, and git-cliff changelog generation on pull requests and pushes to main/master.
+We use [lefthook](https://lefthook.dev/) with the Ruby
+[commitlint](https://github.com/arandilopez/commitlint) gem to enforce
+Conventional Commits on every commit. We also use
+[Standard Ruby](https://standardrb.com/) to keep code style consistent. CI
+validates commit messages, Standard Ruby, tests, and git-cliff changelog
+generation on pull requests and pushes to main/master.
 
 Run the hook installer once per clone:
 
@@ -325,11 +341,16 @@ bundle exec lefthook install
 
 ## Release
 
-Releases are tag-driven and published by GitHub Actions to RubyGems. Local release commands never publish directly.
+Releases are tag-driven and published by GitHub Actions to RubyGems.
+Local release commands never publish directly.
 
-Install [git-cliff](https://git-cliff.org/) locally before preparing a release. The release task regenerates `CHANGELOG.md` from Conventional Commits.
+Install [git-cliff](https://git-cliff.org/) locally before preparing a
+release. The release task prepends the next `CHANGELOG.md` section from
+Conventional Commits.
 
-Before preparing a release, make sure you are on `main` or `master` with a clean worktree.
+Before preparing a release, make sure you are on `main` or `master` with a
+clean worktree. If the release contains a breaking public-contract change,
+update `UPGRADE.md` with the host-app migration steps first.
 
 Then run one of:
 
@@ -342,12 +363,13 @@ bundle exec rake 'release:prepare[0.1.0]'
 
 The task will:
 
-1. Regenerate `CHANGELOG.md` with `git-cliff`.
+1. Prepend the next `CHANGELOG.md` section with `git-cliff`.
 1. Update `lib/indexmap/version.rb`.
 1. Commit the release changes.
 1. Create and push the `vX.Y.Z` tag.
 
-The `Release` workflow then runs tests, publishes the gem to RubyGems, and creates the GitHub release from the changelog entry.
+The `Release` workflow then runs tests, publishes the gem to RubyGems,
+and creates the GitHub release from the changelog entry.
 
 ## License
 

data/lib/indexmap/configuration.rb

@@ -4,7 +4,7 @@ module Indexmap
   class Configuration
     VALID_FORMATS = %i[index single_file].freeze
 
-    attr_writer :base_url, :entries, :format, :index_filename, :public_path, :sections
+    attr_writer :base_url, :entries, :format, :index_filename, :sections, :storage
 
     def initialize
       @format = :index
@@ -38,11 +38,8 @@ module Indexmap
       @index_now ||= IndexNowConfiguration.new
     end
 
-    def public_path
-      value = resolve(@public_path)
-      return Pathname("public") if value.nil?
-
-      Pathname(value)
+    def storage
+      resolve(@storage) || Storage::Filesystem.new(path: "public", public_url: base_url)
     end
 
     def sections

data/lib/indexmap/creator.rb

@@ -1,74 +1,61 @@
 # frozen_string_literal: true
 
 require "nokogiri"
-require "tmpdir"
 
 module Indexmap
   class Creator
-    ValidationConfiguration = Struct.new(:base_url, keyword_init: true)
+    ValidationConfiguration = Struct.new(:base_url, :index_filename, :storage, keyword_init: true)
 
     def initialize(output:)
       @output = output
     end
 
     def create
-      FileUtils.mkdir_p(output.public_path.dirname)
-
-      Dir.mktmpdir("indexmap", output.public_path.dirname) do |dir|
-        staging_path = Pathname(dir)
-        written_files = write_to(staging_path)
-        sitemap_files = sitemap_files_in(staging_path)
-
-        format(sitemap_files)
-        validate(staging_path.join(output.index_filename))
-
-        publish(sitemap_files)
-        written_files.map { |path| output.public_path.join(path.basename) }
-      end
+      files = format(write)
+      validate(files)
+      publish(files)
+      files.map(&:filename)
     end
 
     private
 
     attr_reader :output
 
-    def write_to(staging_path)
-      output.writer.tap do |writer|
-        writer.public_path = staging_path
-      end.write
-    end
-
-    def sitemap_files_in(path)
-      path.glob("sitemap*.xml").sort
+    def write
+      output.writer.write
     end
 
     def format(files)
-      files.each do |file_path|
+      files.map do |file|
         document = Nokogiri::XML(
-          file_path.read,
+          file.body,
           nil,
           nil,
           Nokogiri::XML::ParseOptions::DEFAULT_XML | Nokogiri::XML::ParseOptions::NOBLANKS
         )
         save_options = Nokogiri::XML::Node::SaveOptions::FORMAT | Nokogiri::XML::Node::SaveOptions::AS_XML
 
-        file_path.write(document.to_xml(indent: 2, save_with: save_options))
+        Storage::File.new(
+          filename: file.filename,
+          body: document.to_xml(indent: 2, save_with: save_options),
+          content_type: file.content_type
+        )
       end
     end
 
-    def validate(index_path)
+    def validate(files)
       Validator.new(
-        configuration: ValidationConfiguration.new(base_url: output.base_url),
-        path: index_path
+        configuration: ValidationConfiguration.new(
+          base_url: output.base_url,
+          index_filename: output.index_filename,
+          storage: Storage::Memory.new(files)
+        )
       ).validate!
     end
 
     def publish(files)
-      FileUtils.mkdir_p(output.public_path)
-
-      files.map do |file_path|
-        final_path = output.public_path.join(file_path.basename)
-        File.rename(file_path, final_path)
-        final_path
+      files.each do |file|
+        output.storage.write(file.filename, file.body, content_type: file.content_type)
       end
     end
   end

data/lib/indexmap/index_now_configuration.rb

@@ -5,7 +5,7 @@ module Indexmap
     DEFAULT_ENDPOINT = "https://api.indexnow.org"
     DEFAULT_MAX_URLS_PER_REQUEST = 500
 
-    attr_writer :dry_run, :endpoint, :key, :key_path, :max_urls_per_request
+    attr_writer :dry_run, :endpoint, :key, :key_filename, :max_urls_per_request, :write_key_file
 
     def dry_run?
       value = resolve(@dry_run)
@@ -21,12 +21,19 @@ module Indexmap
       resolve(@key)
     end
 
-    def key_path(public_path:, key: self.key)
-      configured_path = resolve(@key_path)
-      return Pathname(configured_path) unless configured_path.to_s.strip.empty?
+    def write_key_file?
+      value = resolve(@write_key_file)
+      return !key.to_s.strip.empty? if value.nil?
+
+      value == true || value.to_s == "1"
+    end
+
+    def key_filename(key: self.key)
+      configured_filename = resolve(@key_filename)
+      return configured_filename unless configured_filename.to_s.strip.empty?
       return if key.to_s.strip.empty?
 
-      Pathname(public_path).join("#{key}.txt")
+      "#{key}.txt"
     end
 
     def max_urls_per_request

data/lib/indexmap/output.rb

@@ -4,7 +4,7 @@ module Indexmap
   class Output
     VALID_FORMATS = %i[index single_file].freeze
 
-    attr_writer :base_url, :entries, :format, :index_filename, :public_path, :sections
+    attr_writer :base_url, :entries, :format, :index_filename, :sections
 
     def initialize(configuration:)
       @configuration = configuration
@@ -29,9 +29,8 @@ module Indexmap
       resolve(@index_filename) || configuration.index_filename
     end
 
-    def public_path
-      value = resolve(@public_path) || configuration.public_path
-      Pathname(value)
+    def storage
+      configuration.storage
     end
 
     def sections
@@ -57,7 +56,6 @@ module Indexmap
         entries: entries,
         format: format,
         sections: sections,
-        public_path: public_path,
         base_url: base_url,
         index_filename: index_filename
       )