Include a description in llms.txt

Author: josevalim

lib/ex_doc.ex

@@ -75,6 +75,9 @@ defmodule ExDoc do
       ExDoc will by default include all dependencies and assume they are hosted on
       HexDocs. This can be overridden by your own values. Example: `[plug: "https://myserver/plug/"]`
 
+    * `:description` - A brief description of the project, currently included in Hex.pm and the generated
+      `llms.txt` file
+
     * `:extra_section` - String that defines the section title of the additional
       Markdown and plain text pages; default: "Pages". Example: "Guides"
 

lib/ex_doc/formatter/config.ex

@@ -39,6 +39,7 @@ defmodule ExDoc.Formatter.Config do
             authors: nil,
             package: nil,
             title: nil,
+            description: nil,
             nest_modules_by_prefix: [],
             before_closing_head_tag: &__MODULE__.before_closing_head_tag/1,
             before_closing_body_tag: &__MODULE__.before_closing_body_tag/1,
@@ -72,6 +73,7 @@ defmodule ExDoc.Formatter.Config do
           authors: nil | [String.t()],
           package: :atom | nil,
           title: nil | String.t(),
+          description: nil | String.t(),
           nest_modules_by_prefix: [String.t()],
           before_closing_head_tag: (atom() -> String.t()) | mfa() | map(),
           before_closing_body_tag: (atom() -> String.t()) | mfa() | map(),
@@ -144,6 +146,7 @@ defmodule ExDoc.Formatter.Config do
         :authors,
         :package,
         :title,
+        :description,
         :apps,
         :deps
       ])

lib/ex_doc/formatter/markdown.ex

@@ -34,7 +34,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
     extras = group_by_group(extras)
 
     content =
-      Templates.nav_template(config, modules, mix_tasks, extras, "Table of Contents")
+      Templates.llms_txt_template(config, modules, mix_tasks, extras)
       |> normalize_output()
 
     filename = "llms.txt"
@@ -51,7 +51,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
     mix_tasks = group_by_group(tasks)
 
     content =
-      Templates.nav_template(config, modules, mix_tasks, [], "API Reference")
+      Templates.api_reference_template(config, modules, mix_tasks)
       |> normalize_output()
 
     filename = "api-reference.md"

lib/ex_doc/formatter/markdown/templates.ex

@@ -33,9 +33,17 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
 
   EEx.function_from_file(
     :def,
-    :nav_template,
-    Path.expand("templates/nav_template.eex", __DIR__),
-    [:config, :modules, :mix_tasks, :extras, :title],
+    :api_reference_template,
+    Path.expand("templates/api_reference_template.eex", __DIR__),
+    [:config, :modules, :mix_tasks],
+    trim: true
+  )
+
+  EEx.function_from_file(
+    :def,
+    :llms_txt_template,
+    Path.expand("templates/llms_txt_template.eex", __DIR__),
+    [:config, :modules, :mix_tasks, :extras],
     trim: true
   )
 

lib/ex_doc/formatter/markdown/templates/api_reference_template.eex

@@ -0,0 +1,3 @@
+# <%= config.project %> v<%= config.version %> - API Reference
+<%= nav_group_template "Modules", modules %>
+<%= nav_group_template "Mix Tasks", mix_tasks %>

…tter/markdown/templates/nav_template.eex …markdown/templates/llms_txt_template.eexlib/ex_doc/formatter/markdown/templates/nav_template.eex renamed to lib/ex_doc/formatter/markdown/templates/llms_txt_template.eex lib/ex_doc/formatter/markdown/templates/nav_template.eex renamed to lib/ex_doc/formatter/markdown/templates/llms_txt_template.eex

@@ -1,4 +1,8 @@
-# <%= config.project %> v<%= config.version %> - <%= title %>
+# <%= config.project %> v<%= config.version %> - Table of Contents
+<%= if config.description do %>
+<%= config.description %>
+
+<% end %>
 <%= nav_group_template config.extra_section, extras %>
 <%= nav_group_template "Modules", modules %>
 <%= nav_group_template "Mix Tasks", mix_tasks %>

lib/mix/tasks/docs.ex

@@ -135,6 +135,8 @@ defmodule Mix.Tasks.Docs do
       |> normalize_source_url(config)
       # accepted at root level config
       |> normalize_homepage_url(config)
+      # accepted at root level config
+      |> normalize_description(config)
       |> normalize_apps(config)
       |> normalize_main()
       |> normalize_deps()
@@ -228,6 +230,14 @@ defmodule Mix.Tasks.Docs do
     end
   end
 
+  defp normalize_description(options, config) do
+    if description = config[:description] do
+      Keyword.put(options, :description, description)
+    else
+      options
+    end
+  end
+
   defp source_beams(options, config) do
     if Mix.Project.umbrella?(config) do
       umbrella_compile_paths(Keyword.get(options, :ignore_apps, []))

test/ex_doc/formatter/markdown_test.exs

@@ -215,6 +215,25 @@ defmodule ExDoc.Formatter.MarkdownTest do
       refute content =~ "## Pages"
       refute content =~ "## Guides"
     end
+
+    test "includes description when provided", %{tmp_dir: tmp_dir} = context do
+      config =
+        config(context,
+          extras: ["test/fixtures/README.md"],
+          description: "A documentation generation tool for Elixir"
+        )
+
+      generate(config)
+      content = File.read!(tmp_dir <> "/llms.txt")
+
+      assert content =~ "# Elixir v1.0.1 - Table of Contents"
+      assert content =~ "A documentation generation tool for Elixir"
+
+      # Description should not appear in api-reference.md
+      api_content = File.read!(tmp_dir <> "/api-reference.md")
+      assert api_content =~ "# Elixir v1.0.1 - API Reference"
+      refute api_content =~ "A documentation generation tool for Elixir"
+    end
   end
 
   describe "api_reference" do