mdtoc 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c01cef42824ceeae479dc235cbe2c7565c2d6ef045074c8d55b34a821ee719d
-  data.tar.gz: c25c67f2bf841dd9e1e3bb6a632035693299e7a53367b5dd255ecfbc125adab2
+  metadata.gz: f53365d2172397bc4b50a26f88ce05d13c8766453b56c96fd1513151b2d72cad
+  data.tar.gz: c49f859803c2bf3928c51f70535ba35a9bffda3ccc69457713977497c6a50f6e
 SHA512:
-  metadata.gz: 603bec1ab105a7438bb2d0c2e4fb0c7eead9c63b57bfe33ca9354b05458d435805ce614cd11549527749092f2cffdc1289691a177b3c86161bac714f877c3eb7
-  data.tar.gz: 6bb0b63c4217f899d2277ba35baf7966cd97219e88f111c7a842b535108c698ac0260c0cc1f2c7e24858c9464a9cac333ea1fa4a7244104b051ba3184ed326bd
+  metadata.gz: de596f6886429e537d249cc2c2516521cfb23ee8c407f002348a68fe93b3de30f0b6e4809d64c5c2e75858e33791e4507d9060c35c79a8f0459202c105e54b73
+  data.tar.gz: 8da62161d757e8be2c7970ed076b58ea1dbc0b1416e35d497dbc5545faf84764ab88e08895f21c3995e98acd2c1f0f88bec4c9b96b5bcb3f27ad6a80ef07b88e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 andornaut
+
+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,113 @@
+# mdtoc - Markdown Table of Contents
+
+Read Markdown files and output a table of contents.
+
+## Installation
+
+Requirements:
+
+* [Ruby](https://www.ruby-lang.org/en/) (see [.ruby-version](./.ruby-version))
+
+```bash
+gem install mdtoc
+```
+
+## Usage
+
+```bash
+mdtoc --help
+Usage: mdtoc [options] files or directories...
+    -h, --help                       Show this message
+    -o, --output PATH                Update a table of contents in the file at PATH
+    -a, --[no-]append                Append to the --output file if a <!-- mdtoc --> tag isn't found
+    -c, --[no-]create                Create the --output file if it does not exist
+```
+
+1. Add a `<!-- mdtoc -->` tag to a Markdown file.
+
+    ```bash
+    echo '<!-- mdtoc -->' >> README.md
+    ```
+
+2. Run `mdtoc` and specify input files or directories (eg. the "test/samples" directory) and an output file (eg. "README.md").
+
+    ```bash
+    mdtoc -aco README.md test/samples
+    ```
+
+## Example Rakefile
+
+Create a `Rakefile` with the contents below, then run
+[`rake`](https://github.com/ruby/rake) to:
+
+* `git pull`
+* `git add` any `*.md` files
+* Run `mdtoc` to update the generated table of contents in the ./README.md file
+* Git commit and push any changes
+
+```ruby
+task default: %w[mdtoc]
+
+desc 'Update Markdown table of contents and push changes to the git repository'
+task :mdtoc do
+  command = <<~CMD
+    set -e
+    if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
+      echo 'Error: conflicts exist' >&2
+      exit 1
+    fi
+    mdtoc --append --create --output README.md docs/
+    git add *.md **/*.md
+    git commit -qm 'Update TOC' || true
+    git pull
+    git push
+  CMD
+  sh command, verbose: false do |ok, status|
+    unless ok
+      fail "Failed with status: #{status.exitstatus}"
+    end
+  end
+end
+```
+
+See [andornaut/til](https://github.com/andornaut/til/blob/master/Rakefile) for an example.
+
+## Development
+
+### Setup
+
+Requirements:
+
+* [Bundler](https://bundler.io/)
+* [chruby](https://github.com/postmodern/chruby) (recommended)
+
+```bash
+# Setup development environment
+bin/setup
+```
+
+### Tasks
+
+```bash
+# List rake tasks
+rake -T
+rake build                    # Build gem into the pkg directory
+rake default                  # Run the build, rubocop, sorbet and test tasks
+rake install                  # Build and install gem into system gems
+rake rubocop                  # Run RuboCop
+rake sorbet                   # Run the Sorbet type checker
+rake test                     # Run tests
+
+# Run mdtoc with test inputs
+ruby -Ilib bin/mdtoc test/samples
+
+# Run mdtoc with test inputs, and write to a newly created output file
+f=$(mktemp) && ruby -Ilib bin/mdtoc -aco ${f} test/samples ; cat ${f}
+```
+
+### Publishing
+
+1. Bump version in `lib/mdtoc/version.rb`
+2. Run `bundle install` to update `Gemfile.lock`
+3. Commit the changes
+4. Run `rake release` to publish the gem to RubyGems, create the git tag, and push

data/bin/setup

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fileutils'
+
+# path to your application root.
+APP_ROOT = File.expand_path('..', __dir__)
+
+def system!(*args)
+  system(*args) || abort("
+== Command #{args} failed ==")
+end
+
+FileUtils.chdir APP_ROOT do
+  # This script is a way to set up a development environment or update your current one.
+  # You can run it with `bin/setup`.
+
+  puts '== Installing dependencies =='
+  system! 'gem install bundler --conservative'
+  system('bundle check') || system!('bundle install')
+
+  puts "
+== Removing old RBIs =="
+  FileUtils.rm_rf('sorbet/rbi/gems')
+  FileUtils.rm_rf('sorbet/rbi/todo.rbi')
+
+  puts "
+== Generating RBIs =="
+  system! 'bundle exec tapioca gems'
+
+  puts "
+== Initializing Sorbet =="
+  system! 'bundle exec srb tc'
+
+  puts "
+== Setup complete! =="
+end

data/lib/mdtoc/markdown/header.rb

@@ -9,6 +9,9 @@ module Mdtoc
     class Header
       extend T::Sig
 
+      sig { returns(Integer) }
+      attr_accessor :depth
+
       sig { params(depth: Integer, label: String, url: String).void }
       def initialize(depth, label, url)
         raise ArgumentError, "Header depth must be >= 0, but was #{depth}" if depth.negative?

data/lib/mdtoc/node.rb

@@ -26,9 +26,12 @@ module Mdtoc
 
       sig { params(paths: T::Array[String]).returns(String) }
       def render(paths)
-        paths
-          .flat_map { |path| for_path(path).headers }
-          .join("\n")
+        headers = paths.flat_map { |path| for_path(path).headers }
+        min_depth = headers.map(&:depth).min || 0
+        if min_depth.positive?
+          headers.each { |h| h.depth -= min_depth }
+        end
+        headers.join("\n")
       end
     end
 

data/lib/mdtoc/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mdtoc
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mdtoc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - andornaut
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-03 00:00:00.000000000 Z
+date: 2026-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.25'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.25'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -72,28 +72,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
 - !ruby/object:Gem::Dependency
   name: unparser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.8.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -126,7 +126,7 @@ description: |
   ## Usage
 
   ```bash
-  $ mdtoc --help
+  mdtoc --help
   Usage: mdtoc [options] files or directories...
       -h, --help                       Show this message
       -o, --output PATH                Update a table of contents in the file at PATH
@@ -136,23 +136,23 @@ description: |
 
   1. Add a `<!-- mdtoc -->` tag to a Markdown file.
 
-    ```bash
-    echo '<!-- mdtoc -->' >> README.md
-    ```
+      ```bash
+      echo '<!-- mdtoc -->' >> README.md
+      ```
 
   2. Run `mdtoc` and specify input files or directories (eg. the "test/samples" directory) and an output file (eg. "README.md").
 
-    ```bash
-    mdtoc -aco README.md test/samples
-    ```
+      ```bash
+      mdtoc -aco README.md test/samples
+      ```
 
   ## Example Rakefile
 
   Create a `Rakefile` with the contents below, then run
   [`rake`](https://github.com/ruby/rake) to:
 
-  * `git pullgem push pkg/mdtoc-0.2.0.gem`
-  * `git add` any *.md files
+  * `git pull`
+  * `git add` any `*.md` files
   * Run `mdtoc` to update the generated table of contents in the ./README.md file
   * Git commit and push any changes
 
@@ -201,33 +201,37 @@ description: |
 
   ```bash
   # List rake tasks
-  $ rake -T
+  rake -T
   rake build                    # Build gem into the pkg directory
   rake default                  # Run the build, rubocop, sorbet and test tasks
   rake install                  # Build and install gem into system gems
   rake rubocop                  # Run RuboCop
   rake sorbet                   # Run the Sorbet type checker
   rake test                     # Run tests
-  ```
+
   # Run mdtoc with test inputs
-  $ ruby -Ilib bin/mdtoc test/samples
+  ruby -Ilib bin/mdtoc test/samples
 
   # Run mdtoc with test inputs, and write to a newly created output file
-  $ f=$(mktemp) && ruby -Ilib bin/mdtoc -aco ${f} test/samples ; cat ${f}
+  f=$(mktemp) && ruby -Ilib bin/mdtoc -aco ${f} test/samples ; cat ${f}
   ```
 
   ### Publishing
 
-  ```bash
-  rake release
-  ```
+  1. Bump version in `lib/mdtoc/version.rb`
+  2. Run `bundle install` to update `Gemfile.lock`
+  3. Commit the changes
+  4. Run `rake release` to publish the gem to RubyGems, create the git tag, and push
 email:
 executables:
 - mdtoc
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - bin/mdtoc
+- bin/setup
 - lib/mdtoc.rb
 - lib/mdtoc/cli.rb
 - lib/mdtoc/markdown/fragment_generator.rb
@@ -249,7 +253,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.2
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="