Update docs and rename File.request -> File.read.

examples/docs/src/Article.elm

@@ -37,7 +37,7 @@ allMetadata =
                         (\{ filePath, slug } ->
                             DataSource.map2 Tuple.pair
                                 (DataSource.succeed <| Route.Blog__Slug_ { slug = slug })
-                                (StaticFile.request filePath (StaticFile.frontmatter frontmatterDecoder))
+                                (StaticFile.read filePath (StaticFile.frontmatter frontmatterDecoder))
                         )
             )
         |> DataSource.resolve

examples/docs/src/Page/Blog/Slug_.elm

@@ -231,7 +231,7 @@ type alias Data =
 
 data : RouteParams -> DataSource.DataSource Data
 data route =
-    StaticFile.request
+    StaticFile.read
         ("content/blog/" ++ route.slug ++ ".md")
         (OptimizedDecoder.map2 Data
             (StaticFile.body

examples/docs/src/Page/Docs/Section__.elm

@@ -132,7 +132,7 @@ titleForSection section =
     Glob.expectUniqueMatch (findBySlug section.slug)
         |> DataSource.andThen
             (\filePath ->
-                DataSource.File.request filePath
+                DataSource.File.read filePath
                     (markdownBodyDecoder
                         |> OptimizedDecoder.map
                             (\blocks ->
@@ -289,7 +289,7 @@ pageBody routeParams =
     Glob.expectUniqueMatch (findBySlug slug)
         |> DataSource.andThen
             (\filePath ->
-                DataSource.File.request filePath
+                DataSource.File.read filePath
                     markdownBodyDecoder
             )
 

examples/docs/src/Page/Projects.elm

@@ -91,7 +91,7 @@ data =
     Glob.succeed
         (\projectName filePath ->
             DataSource.map2 (Project projectName)
-                (DataSource.File.request filePath DataSource.File.body)
+                (DataSource.File.read filePath DataSource.File.body)
                 (repo projectName)
         )
         |> Glob.match (Glob.literal "projects/")

examples/docs/src/TableOfContents.elm

@@ -23,7 +23,7 @@ dataSource docFiles =
                 sections
                     |> List.map
                         (\section ->
-                            DataSource.File.request
+                            DataSource.File.read
                                 section.filePath
                                 (headingsDecoder section.slug)
                         )

examples/routing/src/Page/Slide/Number_.elm

@@ -124,7 +124,7 @@ data routeParams =
 
 slideBody : RouteParams -> DataSource.DataSource (List (Html.Html Msg))
 slideBody route =
-    DataSource.File.request
+    DataSource.File.read
         "slides.md"
         (DataSource.File.body
             |> OptimizedDecoder.andThen
@@ -150,7 +150,7 @@ slideBody route =
 
 slideCount : DataSource.DataSource Int
 slideCount =
-    DataSource.File.request "slides.md"
+    DataSource.File.read "slides.md"
         (DataSource.File.body
             |> OptimizedDecoder.andThen
                 (\rawBody ->

examples/slides/src/Page/Slide/Number_.elm

@@ -122,7 +122,7 @@ data routeParams =
 
 slideBody : RouteParams -> DataSource.DataSource (List (Html.Html Msg))
 slideBody route =
-    DataSource.File.request
+    DataSource.File.read
         "slides.md"
         (DataSource.File.body
             |> OptimizedDecoder.andThen
@@ -148,7 +148,7 @@ slideBody route =
 
 slideCount : DataSource.DataSource Int
 slideCount =
-    DataSource.File.request "slides.md"
+    DataSource.File.read "slides.md"
         (DataSource.File.body
             |> OptimizedDecoder.andThen
                 (\rawBody ->

src/DataSource/File.elm

@@ -1,24 +1,80 @@
-module DataSource.File exposing (body, frontmatter, glob, rawFile, request)
+module DataSource.File exposing
+    ( read
+    , body, frontmatter, rawFile
+    )
 
-{-|
+{-| This module lets you read files from the local filesystem as a [`DataSource`](DataSource#DataSource).
 
-@docs body, frontmatter, glob, rawFile, request
+@docs read
+
+@docs body, frontmatter, rawFile
 
 -}
 
-import DataSource
+import DataSource exposing (DataSource)
 import DataSource.Http
 import OptimizedDecoder exposing (Decoder)
 import Secrets
 
 
-{-| -}
+{-| Frontmatter is a convention used to keep metadata in a file between `---`'s.
+
+For example, you might have a file called `blog/hello-world.md` with this content:
+
+```markdown
+---
+title: Hello, World!
+draft: true
+---
+Hey there! This is my first post :)
+```
+
+The frontmatter is in the [YAML format](https://en.wikipedia.org/wiki/YAML) here.
+You can also use JSON in your elm-pages frontmatter.
+
+Whether it's YAML or JSON, you use an `OptimizedDecoder` to decode your frontmatter, so it feels just like using
+plain old JSON in Elm.
+
+    import DataSource exposing (DataSource)
+    import DataSource.File as File
+    import OptimizedDecoder as Decode exposing (Decoder)
+
+    blogPost : DataSource ( String, BlogPostMetadata )
+    blogPost =
+        File.read "blog/hello-world.md"
+            (Decode.map2 Tuple.pair
+                (File.frontmatter blogPostDecoder)
+                File.body
+            )
+
+    type alias BlogPostMetadata =
+        { title : String
+        , draft : Bool
+        }
+
+    blogPostDecoder : Decoder BlogPostMetadata
+    blogPostDecoder =
+        Decode.map2 BlogPostMetadata
+            (Decode.field "title" Decode.string)
+            (Decode.field "draft" Decode.bool)
+
+This will give us a DataSource that results in the following value:
+
+    value =
+        ( "Hey there! This is my first post :)"
+        , { title = "Hello, World!"
+          , draft = True
+          }
+        )
+
+-}
 frontmatter : Decoder frontmatter -> Decoder frontmatter
 frontmatter frontmatterDecoder =
     OptimizedDecoder.field "parsedFrontmatter" frontmatterDecoder
 
 
-{-| -}
+{-| Gives us the file's content without stripping off frontmatter.
+-}
 rawFile : Decoder String
 rawFile =
     OptimizedDecoder.field "rawFile" OptimizedDecoder.string
@@ -30,14 +86,28 @@ body =
     OptimizedDecoder.field "withoutFrontmatter" OptimizedDecoder.string
 
 
-{-| -}
+{-| Read a file in as a [`DataSource`](DataSource#DataSource). You can directly read a file path,
-request : String -> Decoder a -> DataSource.DataSource a
+relative to the root of your `elm-pages` project (next to the `elm.json` file and `src/` directory).
-request filePath =
+
+You could read your `elm.json` file in your project like this:
+
+    import DataSource exposing (DataSource)
+    import DataSource.File as File
+
+    elmJsonFile : DataSource String
+    elmJsonFile =
+        File.read "elm.json" File.rawFile
+
+The `OptimizedDecoder.Decoder` argument can use any of the `Decoder` types in this module:
+
+  - [`rawBody`](#rawBody)
+  - [`body`](#body)
+  - [`frontmatter`](#frontmatter)
+
+Often you'll want to combine two together. For example, if you're reading the `frontmatter` and `body` from a file
+(see the example for [`frontmatter`](#frontmatter)).
+
+-}
+read : String -> Decoder a -> DataSource a
+read filePath =
     DataSource.Http.get (Secrets.succeed <| "file://" ++ filePath)
-
-
-{-| -}
-glob : String -> DataSource.DataSource (List String)
-glob pattern =
-    DataSource.Http.get (Secrets.succeed <| "glob://" ++ pattern)
-        (OptimizedDecoder.list OptimizedDecoder.string)