llm-docs-builder 0.13.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a55f2ba08f239388d3f4834df0c1caeef9c138278726b442f6533e000a3554c
-  data.tar.gz: 173e4950404e3a4b83bd5213520a29b5b6f70b374dd18c58a8374c9b5bf55b21
+  metadata.gz: c9ce6fbe87a426d69139719ecd76489c5aed030517167758ea0b2df452f3d636
+  data.tar.gz: 9ce3bfab8d25b4c3a9f11b899f20038da89463eb82ffde1b69106ce4934377c8
 SHA512:
-  metadata.gz: d8769c0a92e29025165900ff3a1c65b1acbd42b51b8f6402353c157dfd4755ddd84dce8fdb26c334d4cba456c04f83af322ceb9fb554aea4ff4ac3a5330f81c5
-  data.tar.gz: 305ea0aa8cc44144079988e4faf80125fbf765331d3801ec8273f183c9b77cbc1430bf5b10eba5b09f0068ca526c4bc2b5d8a90a48179583270de1f62df12f77
+  metadata.gz: 9f98c868bfde76f265dd69854a43da9c67b48f5310234611105a6dec00a62236070461484b52c8e08c85cf9fd7bfcbffea0a85e92ce0943ac879b9dc532d3b77
+  data.tar.gz: 6a6340a373df54139338af837a7755b3148fdaef4d58810779cd88b5e2c5f1cca6edda231cee9e3cdace9cc60d465b14e0d78ecf41c3e338fb9fc40029d3f4c0

data/.github/workflows/ci.yml

@@ -19,10 +19,12 @@ jobs:
   specs:
     timeout-minutes: 15
     runs-on: ubuntu-latest
+    continue-on-error: ${{ contains(matrix.ruby, 'preview') || contains(matrix.ruby, 'rc') }}
     strategy:
       fail-fast: false
       matrix:
         ruby:
+          - '4.1.0-preview1'
           - '4.0'
           - '3.4'
           - '3.3'
@@ -30,12 +32,16 @@ jobs:
           - ruby: '4.0'
             coverage: 'true'
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
+      - name: Remove Gemfile.lock for Ruby preview versions
+        if: contains(matrix.ruby, 'preview') || contains(matrix.ruby, 'rc')
+        run: rm -f Gemfile.lock
+
       - name: Set up Ruby
-        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
@@ -58,11 +64,11 @@ jobs:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - name: Set up Ruby
-        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
         with:
-          ruby-version: '4.0.3'
+          ruby-version: '4.0.9'
           bundler-cache: true
       - name: Run yard-lint
         run: bundle exec yard-lint lib/
@@ -71,11 +77,11 @@ jobs:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
       - name: Set up Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: '20'
           cache: 'npm'

data/.github/workflows/docker.yml

@@ -25,13 +25,13 @@ jobs:
       id-token: write
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
         with:
           images: |
             mensfeld/llm-docs-builder
@@ -45,28 +45,28 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to Docker Hub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           platforms: linux/amd64,linux/arm64

data/.github/workflows/push.yml

@@ -19,12 +19,12 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
         with:
           bundler-cache: false
 
@@ -32,4 +32,4 @@ jobs:
         run: |
           bundle install --jobs 4 --retry 3
 
-      - uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0
+      - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1

data/.ruby-version

@@ -1 +1 @@
-4.0.3
+4.0.9

data/.yard-lint.yml

@@ -62,6 +62,34 @@ Documentation/BlankLineBeforeDefinition:
     SingleBlankLine: true
     OrphanedDocs: true
 
+Documentation/DuplicateNamespaceComment:
+  Description: Detects namespaces documented with a YARD comment in more than one file.
+  Enabled: true
+  Severity: error
+
+Documentation/UnderfilledLines:
+  Description: Detects documentation prose that wraps too early and wastes horizontal space.
+  Enabled: true
+  Severity: error
+  # Aligned with RuboCop's Layout/LineLength so documentation prose wraps to the same
+  # width as code.
+  MaxLength: 120
+
+Documentation/LineLength:
+  Description: Detects documentation lines that exceed the maximum length.
+  Enabled: true
+  Severity: error
+  # Aligned with RuboCop's Layout/LineLength.
+  MaxLength: 120
+
+Documentation/TextSubstitution:
+  Description: Detects em/en-dashes in documentation and replaces them with hyphens.
+  Enabled: true
+  Severity: error
+  Substitutions:
+    "—": "-"    # em-dash (U+2014)
+    "–": "-"    # en-dash (U+2013)
+
 # Tags validators
 Tags/Order:
   Description: Enforces consistent ordering of YARD tags.
@@ -70,9 +98,15 @@ Tags/Order:
   EnforcedOrder:
   - param
   - option
+  - yield
+  - yieldparam
+  - yieldreturn
   - return
   - raise
+  - see
   - example
+  - note
+  - todo
 
 Tags/InvalidTypes:
   Description: Validates type definitions in @param, @return, @option tags.
@@ -142,7 +176,7 @@ Tags/OptionTags:
 Tags/ExampleSyntax:
   Description: Validates Ruby syntax in @example tags.
   Enabled: true
-  Severity: warning
+  Severity: error
 
 Tags/RedundantParamDescription:
   Description: Detects meaningless parameter descriptions that add no value.

data/CHANGELOG.md

@@ -1,23 +1,55 @@
 # Changelog
 
+## 1.1.0 (2026-11-02)
+- [Enhancement] **Relative Link Resolution** - `base_url` link expansion now resolves relative links like a browser would.
+  - `../` and `./` segments are normalized (`../other.md` → `https://example.com/other.md` instead of `https://example.com/docs/../other.md`).
+  - `bulk-transform` resolves each link from its file's own directory, so `./setup.md` in `guides/intro.md` expands to `<base_url>/guides/setup.md`.
+  - Links starting with `/` resolve from `base_url`; anchors, query strings, absolute URLs and `mailto:`/`tel:`/`ftp:` links are unchanged.
+- [Fix] **llms.txt Paths Are Percent-Encoded** - `generate` now percent-encodes each path segment in `llms.txt` entries, with and without `base_url`.
+  - `docs/my docs/a b.md` gives `my%20docs/a%20b.md`, so names with spaces or parentheses no longer break the Markdown link.
+  - Non-ASCII names are encoded as UTF-8 (`zażółć.md` → `za%C5%BC%C3%B3%C5%82%C4%87.md`).
+- [Fix] **llms.txt Descriptions** - A page description is now always a single line, and the 200-character limit no longer cuts a Markdown link or image in half; a link or image that does not fit is left out.
+- [Fix] **Transformed Files Picked Up as Sources** - `bulk-transform` and `generate` now skip files ending with the transform suffix (`*.llm.md` by default, or `*<suffix>.md`).
+  - A second `bulk-transform` run no longer writes `*.llm.llm.md` files.
+  - `generate` lists each page once, from its source file, instead of listing both `README.md` and `README.llm.md`.
+  - Source files whose names end with the suffix (e.g. `notes.llm.md`) are skipped too. An empty suffix skips nothing.
+- [Fix] **Angle-Bracket Link Destinations** - `base_url` link expansion now resolves CommonMark `[text](<path with spaces>)` links like other relative links: the brackets are dropped and spaces are percent-encoded (`<../my docs/a b.md>` → `<base_url>/my%20docs/a%20b.md`) instead of producing a broken URL with a stray `>`.
+- [Fix] **Query-Only Links** - `base_url` link expansion now resolves a query-only link like `[q](?tab=2)` to the current page (`guides/sub/page.md` gives `<base_url>/guides/sub/page.md?tab=2`, as RFC 3986 does) instead of the page's directory (`<base_url>/guides/sub/?tab=2`). Anchor-only links like `#self` are unchanged.
+- [Fix] **`simplify_links` Strips Only One Prefix** - repeated filler prefixes are now all removed, so `Click here to see the docs` becomes `docs` (as documented) instead of `see the`.
+- [Fix] **Links Inside Code Are Rewritten** - link transformations (`base_url` expansion, `convert_urls`, `simplify_links`) no longer change links in fenced code blocks, indented code blocks and inline code spans.
+- [Fix] **`convert_urls` Skips Anchors, Queries and Relative Links** - `.html`/`.htm` URLs followed by an anchor or a query are now converted (`doc.html#sec` → `doc.md#sec`, `doc.html?x=1` → `doc.md?x=1`).
+  - Relative link targets are converted too, also without `base_url` (`[Intro](../intro.html)` → `[Intro](../intro.md)`).
+  - `.html` inside a query or an anchor and targets with a non-HTTP scheme (`mailto:`, `ftp:`, `sftp:`, `file:`, ...) are left unchanged.
+- [Fix] **Links With Brackets in Their Text** - `base_url` link expansion now expands links whose text holds brackets, nested up to two levels deep (`[a [b] c](../intro.md)`), and linked images like `[![alt](../img/a.png)](../intro.md)`, where both the image and the outer link are now expanded. Before, such links stayed relative, and a linked image got only its image expanded.
+- [Fix] **Links With Any URI Scheme** - `base_url` link expansion now leaves every link with a URI scheme unchanged, in any case (`HTTPS://`, `Mailto:`, `sftp:`, `ssh:`, `git:`, `irc:`, `urn:`, `data:`, `javascript:`, ...). Before, only lowercase `http`, `https`, `mailto`, `ftp` and `tel` links were kept, and others became broken URLs like `<base_url>/guides/sftp:/host/x`.
+- [Fix] **Link Reference Definitions** - `base_url` link expansion now expands reference-style link definitions (`[id]: ../intro.md "Title"`) like inline links, so `[text][id]`, `[id][]` and `[id]` links no longer stay relative while inline links in the same file are expanded. Titles are kept; definitions with a URI scheme, anchors, footnotes (`[^1]: ...`) and definitions in code are unchanged.
+  - `convert_urls` converts `.html`/`.htm` definition targets too (`[id]: ../intro.html` → `[id]: ../intro.md`).
+- [Fix] **`compare` Web Server Link** - The "Configure your web server" link in the `compare` output now points at the README section "Serving Optimized Docs to AI Bots" (`#serving-optimized-docs-to-ai-bots`) instead of a missing `#serving-optimized-docs` anchor.
+
+## 1.0.0 (2026-08-24)
+- [Fix] **Link Expansion Corrupts Non-HTTP URI Schemes** - `LinkTransformer#expand_relative_links` no longer rewrites `mailto:`, `tel:`, and `ftp:` links into dead `https://...` URLs when `base_url` is set (#165).
+  - Any link whose scheme is in the known absolute-scheme list (`http`, `https`, `mailto`, `ftp`, `tel`) is now left untouched, matching `HtmlToMarkdownConverter`'s `SAFE_URI_SCHEMES`.
+  - Relative links (e.g. `./guide.md`) continue to expand as before.
+- [Enhancement] Add Ruby warning category opt-in to test helpers
+
 ## 0.13.0 (2026-05-11)
 - [Breaking] Dropped Ruby 3.2 support. Minimum required Ruby version is now 3.3.
-- [Fix] **Heading Nesting in Normalize Mode** — Fixed `normalize_headings` producing incorrect heading levels when same-level headings are nested under a parent.
+- [Fix] **Heading Nesting in Normalize Mode** - Fixed `normalize_headings` producing incorrect heading levels when same-level headings are nested under a parent.
   - Consecutive same-level headings (e.g., two `##` headings) now correctly adjust the child's markdown level to be deeper than the parent's (e.g., `##` → `###`)
   - Effective level formula: `max(parent_effective_level + 1, original_level)`
   - ATX closing hashes (`## Title ##`) are now stripped from titles before building hierarchical paths
-- [Fix] **HTML-to-Markdown Section Nesting** — Headings inside nested `<section>` elements now receive adjusted markdown levels based on section nesting depth.
+- [Fix] **HTML-to-Markdown Section Nesting** - Headings inside nested `<section>` elements now receive adjusted markdown levels based on section nesting depth.
   - `<h2>` inside a nested `<section>` under another `<section>` with its own `<h2>` is now correctly rendered as `###` instead of `##`
 
 ## 0.12.0 (2025-11-12)
-- [Feature] **HTML to Markdown Reverse Converter** — Added support for converting HTML content to markdown format.
+- [Feature] **HTML to Markdown Reverse Converter** - Added support for converting HTML content to markdown format.
   - Enables processing of HTML documentation sources
   - Integrates seamlessly with the transformer pipeline
   - Useful for converting web-based docs to markdown for further processing
   - By @Eric-Guo in PR #32.
 
 ## 0.11.0 (2025-11-03)
-- [Feature] **Transform from URL** — The `transform` command now accepts a remote URL via `--url` and processes fetched content through the standard transformer pipeline.
+- [Feature] **Transform from URL** - The `transform` command now accepts a remote URL via `--url` and processes fetched content through the standard transformer pipeline.
   - Example: `llm-docs-builder transform --url https://example.com/docs/page.html`
   - Applies all configured transformations and output options identically to local files
   - By @Eric-Guo and @codex in PR #28.

data/Gemfile

@@ -8,3 +8,7 @@ group :development do
   gem 'pry'
   gem 'yard-lint'
 end
+
+group :test do
+  gem 'warning'
+end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    llm-docs-builder (0.13.0)
+    llm-docs-builder (1.1.0)
       nokogiri (~> 1.17)
       zeitwerk (~> 2.6)
 
@@ -11,30 +11,29 @@ GEM
     ast (2.4.3)
     coderay (1.1.3)
     diff-lcs (1.6.2)
-    docile (1.4.1)
-    io-console (0.8.2)
-    json (2.19.5)
-    language_server-protocol (3.17.0.5)
+    io-console (0.9.4)
+    json (3.0.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     method_source (1.1.0)
     mini_portile2 (2.8.9)
-    nokogiri (1.19.3)
+    nokogiri (1.19.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    parallel (2.1.0)
-    parser (3.3.11.1)
+    parallel (2.2.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
-    pry (0.16.0)
+    pry (0.16.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
       reline (>= 0.6.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.4.2)
-    regexp_parser (2.12.0)
-    reline (0.6.3)
+    regexp_parser (2.13.1)
+    reline (0.7.0)
       io-console (~> 0.5)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -49,8 +48,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.86.1)
-      json (~> 2.3)
+    rubocop (1.91.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -60,24 +59,20 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-progressbar (1.13.0)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    unicode-display_width (3.2.0)
-      unicode-emoji (~> 4.1)
-    unicode-emoji (4.2.0)
-    yard (0.9.43)
-    yard-lint (1.5.1)
+    simplecov (1.3.2)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    warning (1.6.0)
+    yard (0.9.45)
+    yard-lint (1.13.0)
       yard (~> 0.9)
       zeitwerk (~> 2.6)
-    zeitwerk (2.7.5)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   ruby
@@ -89,8 +84,9 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.0)
-  simplecov (~> 0.21)
+  simplecov (~> 1.0)
+  warning
   yard-lint
 
 BUNDLED WITH
-   2.6.9
+  4.0.17

data/README.md

@@ -125,7 +125,7 @@ llm-docs-builder generate --config llm-docs-builder.yml
 ```yaml
 # llm-docs-builder.yml
 docs: ./docs
-base_url: https://myproject.io
+base_url: https://myproject.io  # Base URL for expanding relative links
 title: My Project
 description: Brief description
 body: Optional body content between description and sections
@@ -165,6 +165,12 @@ excludes:
   - "**/drafts/**"
 ```
 
+**Link expansion (`base_url`):** relative links become absolute URLs.
+- Inline links, images (also linked images, `[![alt](a.png)](../intro.md)`) and reference-style definitions (`[a]: ../intro.md`) are expanded. `<path with spaces>` destinations are resolved and their spaces encoded as `%20`.
+- `bulk-transform` resolves links from each file's directory under `docs`. Single-file `transform` (and `LlmDocsBuilder.transform_markdown`) resolves them from `base_url`: with `base_url: https://myproject.io/docs`, `../intro.md` becomes `https://myproject.io/intro.md`.
+- Links starting with `/` resolve from `base_url`. In `bulk-transform`, a query-only link (`[q](?tab=2)`) resolves to the current page (`.../page.md?tab=2`).
+- Left unchanged: links in fenced code, indented code and inline code; anchors (`#x`); protocol-relative URLs (`//cdn.io/a.md`); URLs with any scheme, in any case (`HTTPS:`, `sftp:`, `urn:`, `mailto:`); HTML `<a href>` and `<img src>`.
+
 ## CLI Commands
 
 ```bash
@@ -183,31 +189,34 @@ llm-docs-builder version                  # Show version
 -d, --docs PATH      Documentation path
 -o, --output PATH    Output file
 -u, --url URL        URL for comparison
+-f, --file PATH      Local markdown file for comparison
 -v, --verbose        Detailed output
 ```
 
 ## Serving Optimized Docs to AI Bots
 
-After using `bulk-transform` with `suffix: .llm`, configure your web server to serve optimized versions to AI bots:
+After using `bulk-transform` with `suffix: .llm`, configure your web server to serve optimized versions to AI bots. Pages without an `.llm.md` version are served as is:
 
 **Apache (.htaccess):**
 ```apache
 SetEnvIf User-Agent "(?i)(openai|anthropic|claude|gpt)" IS_LLM_BOT
+RewriteEngine On
 RewriteCond %{ENV:IS_LLM_BOT} !^$
+RewriteCond %{REQUEST_URI} !\.llm\.md$
+RewriteCond %{REQUEST_FILENAME} ^(.+)\.md$
+RewriteCond %1.llm.md -f
 RewriteRule ^(.*)\.md$ $1.llm.md [L]
 ```
 
 **Nginx:**
 ```nginx
-map $http_user_agent $is_llm_bot {
-    default 0;
-    "~*(?i)(openai|anthropic|claude|gpt)" 1;
+map $http_user_agent $llm_suffix {
+    default "";
+    "~*(openai|anthropic|claude|gpt)" ".llm";
 }
 
-location ~ ^/docs/(.*)\.md$ {
-    if ($is_llm_bot) {
-        rewrite ^(.*)\.md$ $1.llm.md last;
-    }
+location ~ ^/docs/(?<doc>.*)\.md$ {
+    try_files /docs/$doc$llm_suffix.md $uri =404;
 }
 ```
 
@@ -258,7 +267,10 @@ api = API.new
 ```markdown
 # API Documentation
 
-[complete API documentation](./api.md)
+
+> Important: This is a note
+
+[Click here to see the complete API documentation](./api.md)
 
 api = API.new
 ```
@@ -411,7 +423,7 @@ All compression features can be used individually for fine-grained control:
 - `generate_toc: true` - Generate table of contents from headings with anchor links
 - `custom_instruction: "text"` - Inject AI context message at document top
 - `simplify_links: true` - Simplify verbose link text (e.g., "Click here to see the docs" → "docs")
-- `convert_urls: true` - Convert `.html`/`.htm` URLs to `.md` format
+- `convert_urls: true` - Convert `.html`/`.htm` URLs to `.md` format, keeping anchors and queries (`../intro.html#x` → `../intro.md#x`): absolute `http(s)` URLs anywhere in the text, and relative link and reference-style definition targets. URLs in code are unchanged
 - `normalize_whitespace: true` - Reduce excessive blank lines and remove trailing whitespace
 
 ## License

data/lib/llm_docs_builder/bulk_transformer.rb

@@ -76,16 +76,19 @@ module LlmDocsBuilder
 
     # Recursively scans the docs directory for markdown files
     #
-    # Skips hidden files (starting with dot) and returns sorted array of paths
+    # Skips hidden files (starting with dot) and already transformed files (ending with
+    # the suffix, e.g. README.llm.md) and returns sorted array of paths
     #
     # @return [Array<String>] paths to markdown files
     def find_markdown_files
       files = []
+      output_ending = "#{options[:suffix]}.md".downcase
 
       Find.find(docs_path) do |path|
         next unless File.file?(path)
         next unless path.match?(/\.md$/i)
         next if File.basename(path).start_with?('.')
+        next if output_ending != '.md' && path.downcase.end_with?(output_ending)
 
         files << path
       end
@@ -109,12 +112,14 @@ module LlmDocsBuilder
 
     # Applies markdown transformations to a single file
     #
-    # Creates MarkdownTransformer instance and delegates transformation
+    # Creates MarkdownTransformer instance and delegates transformation. Passes the file's
+    # path relative to the docs directory so relative links resolve from its own location.
     #
     # @param file_path [String] path to markdown file
     # @return [String] transformed content
     def transform_file(file_path)
-      transformer = MarkdownTransformer.new(file_path, options)
+      source_path = Pathname.new(file_path).relative_path_from(Pathname.new(docs_path)).to_s
+      transformer = MarkdownTransformer.new(file_path, options.merge(source_path: source_path))
       transformer.transform
     end
 

data/lib/llm_docs_builder/cli.rb

@@ -129,8 +129,7 @@ module LlmDocsBuilder
 
     # Generate llms.txt from documentation directory or file
     #
-    # Loads configuration, merges with CLI options, generates llms.txt content,
-    # and optionally validates the output.
+    # Loads configuration, merges with CLI options, generates llms.txt content, and optionally validates the output.
     #
     # @param options [Hash] command options from parse_options
     # @option options [String] :config path to config file

data/lib/llm_docs_builder/generator.rb

@@ -12,6 +12,10 @@ module LlmDocsBuilder
   #
   # @api public
   class Generator
+    # Maximum length of a file description in llms.txt, in characters
+    MAX_DESCRIPTION_LENGTH = 200
+    private_constant :MAX_DESCRIPTION_LENGTH
+
     # @return [String] path to documentation directory or file
     attr_reader :docs_path
 
@@ -27,6 +31,7 @@ module LlmDocsBuilder
     # @option options [String] :description project description (overrides auto-detection)
     # @option options [String] :output output file path for saving
     # @option options [Boolean] :verbose enable verbose output
+    # @option options [String] :suffix suffix of bulk-transformed files to skip (default: '.llm')
     def initialize(docs_path, options = {})
       @docs_path = docs_path
       @options = options
@@ -34,8 +39,7 @@ module LlmDocsBuilder
 
     # Generate llms.txt content from documentation
     #
-    # Scans documentation files, extracts metadata, prioritizes them, and builds a formatted
-    # llms.txt file.
+    # Scans documentation files, extracts metadata, prioritizes them, and builds a formatted llms.txt file.
     #
     # @return [String] generated llms.txt content
     def generate
@@ -69,11 +73,13 @@ module LlmDocsBuilder
 
     # Recursively finds and analyzes markdown files in directory
     #
-    # Sorts by priority (README, guides, etc.) and skips hidden files
+    # Sorts by priority (README, guides, etc.) and skips hidden files and bulk-transformed
+    # files (ending with the suffix, e.g. README.llm.md)
     #
     # @return [Array<Hash>] sorted array of analyzed file metadata
     def find_markdown_files_in_directory
       files = []
+      output_ending = "#{options.fetch(:suffix, '.llm')}.md".downcase
 
       Find.find(docs_path) do |path|
         # Skip hidden directories unless explicitly enabled
@@ -86,6 +92,7 @@ module LlmDocsBuilder
         next unless File.file?(path)
         next unless path.match?(/\.md$/i)
         next if File.basename(path).start_with?('.')
+        next if output_ending != '.md' && path.downcase.end_with?(output_ending)
         next if should_exclude?(path)
 
         files << analyze_file(path)
@@ -158,7 +165,8 @@ module LlmDocsBuilder
 
     # Extracts description from file content
     #
-    # Takes first paragraph after title, truncated to 200 characters
+    # Takes first paragraph after title as a single line, truncated to MAX_DESCRIPTION_LENGTH characters.
+    # A Markdown link or image that would be cut by the limit is dropped entirely.
     #
     # @param content [String] file content
     # @return [String] extracted description
@@ -171,7 +179,62 @@ module LlmDocsBuilder
       # Get first paragraph
       first_paragraph = description_lines.take_while { |line| !line.strip.empty? }
 
-      first_paragraph.join(' ').strip.slice(0, 200)
+      description = first_paragraph.join(' ').gsub(/\s+/, ' ').strip
+      return description if description.length <= MAX_DESCRIPTION_LENGTH
+
+      cut_link = link_spans(description).find do |span|
+        span.begin < MAX_DESCRIPTION_LENGTH && span.end >= MAX_DESCRIPTION_LENGTH
+      end
+
+      return description.slice(0, MAX_DESCRIPTION_LENGTH) unless cut_link
+
+      description.slice(0, cut_link.begin).rstrip
+    end
+
+    # Finds the character ranges of Markdown links and images in text
+    #
+    # Brackets and parentheses are matched by nesting depth, so linked images, nested link text, URLs
+    # with parentheses and reference links are each one range. An unclosed bracket is not a link.
+    #
+    # @param text [String] single-line text
+    # @return [Array<Range>] inclusive index ranges
+    def link_spans(text)
+      closing = closing_indexes(text)
+      spans = []
+      index = 0
+
+      while (start = text.index('[', index))
+        stop = closing[start]
+        index = start + 1
+        next unless stop
+
+        stop = closing[stop + 1] while closing[stop + 1]
+        start -= 1 if start.positive? && text[start - 1] == '!'
+        spans << (start..stop)
+        index = stop + 1
+      end
+
+      spans
+    end
+
+    # Maps the index of each opening bracket or parenthesis to the index of the one that closes it
+    #
+    # @param text [String] text to search
+    # @return [Hash{Integer => Integer}] closing index by opening index, unclosed ones are absent
+    def closing_indexes(text)
+      closing = {}
+      open_indexes = { '[' => [], '(' => [] }
+      pairs = { ']' => '[', ')' => '(' }
+
+      text.each_char.with_index do |char, index|
+        if open_indexes.key?(char)
+          open_indexes[char] << index
+        elsif pairs.key?(char) && (opened = open_indexes[pairs[char]].pop)
+          closing[opened] = index
+        end
+      end
+
+      closing
     end
 
     # Assigns priority to file based on filename patterns
@@ -311,13 +374,18 @@ module LlmDocsBuilder
 
     # Constructs full URL from path using base_url option if provided
     #
+    # Each path segment is percent-encoded, so names with spaces, parentheses or
+    # non-ASCII characters give a valid Markdown link destination.
+    #
     # @param path [String] relative path to file
     # @return [String] full URL or relative path
     def build_url(path)
+      encoded_path = path.split('/').map { |segment| ERB::Util.url_encode(segment) }.join('/')
+
       if (base_url = options[:base_url])
-        File.join(base_url, path)
+        File.join(base_url, encoded_path)
       else
-        path
+        encoded_path
       end
     end