If no pages specified, put index.md in front of other pages

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Documenter.jl changelog
 
+## Version `v0.25.1`
+
+* ![Enhancement][badge-enhancement] When automatically determining the page list (i.e. `pages` is not passed to `makedocs`), Documenter now lists `index.md` before other pages. ([#1355][github-1355])
+
 ## Version `v0.25.0`
 
 * ![Enhancement][badge-enhancement] When deploying with `deploydocs`, any SSH username can now be used (not just `git`), by prepending `username@` to the repository URL in the `repo` argument. ([#1285][github-1285])
@@ -588,6 +592,7 @@
 [github-1339]: https://github.com/JuliaDocs/Documenter.jl/pull/1339
 [github-1344]: https://github.com/JuliaDocs/Documenter.jl/issues/1344
 [github-1345]: https://github.com/JuliaDocs/Documenter.jl/pull/1345
+[github-1355]: https://github.com/JuliaDocs/Documenter.jl/pull/1355
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/Builder.jl

@@ -138,7 +138,7 @@ function Selectors.runner(::Type{SetupBuildDirectory}, doc::Documents.Document)
     # If the user hasn't specified the page list, then we'll just default to a
     # flat list of all the markdown files we found, sorted by the filesystem
     # path (it will group them by subdirectory, among others).
-    userpages = isempty(doc.user.pages) ? sort(mdpages) : doc.user.pages
+    userpages = isempty(doc.user.pages) ? sort(mdpages, lt=lt_page) : doc.user.pages
 
     # Populating the .navtree and .navlist.
     # We need the for loop because we can't assign to the fields of the immutable
@@ -159,6 +159,19 @@ function Selectors.runner(::Type{SetupBuildDirectory}, doc::Documents.Document)
     end
 end
 
+"""
+    lt_page(a::AbstractString, b::AbstractString)
+
+Checks if the page path `a` should come before `b` in a sorted list. Falls back to standard
+string sorting, except for prioritizing `index.md` (i.e. `index.md` always comes first).
+"""
+function lt_page(a, b)
+    # note: length("index.md") == 8
+    a = endswith(a, "index.md") ? chop(a; tail = 8) : a
+    b = endswith(b, "index.md") ? chop(b; tail = 8) : b
+    return a < b
+end
+
 """
 $(SIGNATURES)
 

test/pipeline.jl

@@ -0,0 +1,76 @@
+module PipeLineTests
+using Test
+
+@testset "Builder.lt_page" begin
+    using Documenter.Builder: lt_page
+    # Checks to make sure that only exactly one of a<b, a==b and a>b is true for given a & b
+    iscorrectisless(a,b) = sum([lt_page(a, b), a == b, lt_page(b, a)]) == 1
+    # Test equal strings:
+    for a in ["index.md", "foo/index.md", "foo.md", "bar/foo.md", "foo/bar/baz/qux", "", "α", "α/β", "α/index.md"]
+        @test !lt_page(a, a)
+        @test iscorrectisless(a, a)
+    end
+    # Test less thans
+    for (a, b) in [
+            ("a", "b"), ("α", "β"), ("b", "α"),
+            # index.md takes precedence
+            ("index.md", "a"),
+            ("index.md", "index.mm"),
+            ("index.md", "foo.md"),
+            ("index.md", "bar/foo.md"),
+            # Also in subdirectories:
+            ("foo/index.md", "foo/a"),
+            ("foo/index.md", "foo/index.mm"),
+            ("foo/index.md", "foo/foo.md"),
+            ("foo/index.md", "foo/bar/foo.md"),
+            # But not over stuff that is outside of the subdirectory
+            ("a", "foo/index.md"),
+            ("α", "α/index.md"),
+            ("foo/index.md", "g"),
+            ("bar/index.md", "foo/index.md"),
+            ("bar/qux/index.md", "foo/index.md"),
+        ]
+        @test lt_page(a, b)
+        @test iscorrectisless(a, b)
+    end
+
+    @test sort(["foo", "bar"], lt=lt_page) == ["bar", "foo"]
+    @test sort(["foo", "foo/bar"], lt=lt_page) == ["foo", "foo/bar"]
+    @test sort(["foo", "f/bar"], lt=lt_page) == ["f/bar", "foo"]
+    @test sort(["foo", "index.md"], lt=lt_page) == ["index.md", "foo"]
+    @test sort(["foo.md", "foo/index.md", "index.md", "foo/foo.md"], lt=lt_page) == ["index.md", "foo.md", "foo/index.md", "foo/foo.md"]
+    @test sort(["foo.md", "ϕωω/index.md", "index.md", "foo/foo.md"], lt=lt_page) == ["index.md", "foo.md", "foo/foo.md", "ϕωω/index.md"]
+end
+
+# Docstring signature syntax highlighting tests.
+module HighlightSig
+    using Test
+    import Markdown
+    import Documenter.Expanders: highlightsig!
+
+    @testset "highlightsig!" begin
+        s = """
+                foo(bar::Baz)
+            ---
+                foo(bar::Baz)
+            """
+        original = Markdown.parse(s)
+        md = Markdown.parse(s)
+        highlightsig!(md)
+        @test isempty(original.content[1].language)
+        @test md.content[1].language == "julia"
+        @test original.content[end].language == md.content[end].language
+
+        s = """
+            ```lang
+             foo(bar::Baz)
+            ```
+            """
+        original = Markdown.parse(s)
+        md = Markdown.parse(s)
+        highlightsig!(md)
+        @test original == md
+    end
+end
+
+end

test/runtests.jl

@@ -50,8 +50,8 @@ include("TestUtilities.jl"); using .TestUtilities
     # MDFlatten tests.
     include("mdflatten.jl")
 
-    # Expanders
-    include("expanders.jl")
+    # Main build pipeline (Builder and Expanders modules)
+    include("pipeline.jl")
 
     # HTMLWriter
     include("htmlwriter.jl")