From 1ca83ce52940ba5948e19194835c33ecb2d42561 Mon Sep 17 00:00:00 2001 From: Ryan Haskell-Glatz Date: Sun, 25 Apr 2021 14:36:16 -0500 Subject: [PATCH] reorganize site into two sections --- docs/public/content/examples.md | 30 ++++++++-- .../{guides => examples}/01-hello-world.md | 0 .../content/{guides => examples}/02-pages.md | 0 docs/public/content/examples/03-storage.md | 3 + .../04-authentication.md} | 6 +- docs/public/content/examples/05-testing.md | 3 + docs/public/content/examples/06-npm.md | 3 + docs/public/content/{docs.md => guide.md} | 4 +- docs/public/content/{docs => guide}/cli.md | 58 +++++++++++-------- docs/public/content/{docs => guide}/pages.md | 4 +- .../public/content/{docs => guide}/routing.md | 2 +- .../content/{docs => guide}/shared-state.md | 4 +- .../content/{docs => guide}/url-requests.md | 2 +- docs/public/content/{docs => guide}/views.md | 0 docs/public/content/guides.md | 7 --- docs/public/content/guides/04-storage.md | 1 - docs/public/content/guides/05-npm.md | 1 - docs/public/style.css | 9 +++ docs/src/Domain/Index.elm | 4 +- .../Pages/{Guides => Examples}/Section_.elm | 2 +- docs/src/Pages/{Docs.elm => Guide.elm} | 2 +- docs/src/Pages/{Docs => Guide}/Section_.elm | 2 +- docs/src/Pages/Guides.elm | 19 ------ docs/src/Pages/NotFound.elm | 2 +- docs/src/UI/Layout.elm | 21 +++++-- 25 files changed, 113 insertions(+), 76 deletions(-) rename docs/public/content/{guides => examples}/01-hello-world.md (100%) rename docs/public/content/{guides => examples}/02-pages.md (100%) create mode 100644 docs/public/content/examples/03-storage.md rename docs/public/content/{guides/03-user-auth.md => examples/04-authentication.md} (96%) create mode 100644 docs/public/content/examples/05-testing.md create mode 100644 docs/public/content/examples/06-npm.md rename docs/public/content/{docs.md => guide.md} (96%) rename docs/public/content/{docs => guide}/cli.md (77%) rename docs/public/content/{docs => guide}/pages.md (98%) rename docs/public/content/{docs => guide}/routing.md (98%) rename docs/public/content/{docs => guide}/shared-state.md (92%) rename docs/public/content/{docs => guide}/url-requests.md (94%) rename docs/public/content/{docs => guide}/views.md (100%) delete mode 100644 docs/public/content/guides.md delete mode 100644 docs/public/content/guides/04-storage.md delete mode 100644 docs/public/content/guides/05-npm.md rename docs/src/Pages/{Guides => Examples}/Section_.elm (79%) rename docs/src/Pages/{Docs.elm => Guide.elm} (82%) rename docs/src/Pages/{Docs => Guide}/Section_.elm (79%) delete mode 100644 docs/src/Pages/Guides.elm diff --git a/docs/public/content/examples.md b/docs/public/content/examples.md index 91019e4..55b3281 100644 --- a/docs/public/content/examples.md +++ b/docs/public/content/examples.md @@ -1,7 +1,29 @@ # Examples -Here are real-world applications using __elm-spa__: +Prefer to learn by example? Wonderful! The source code for all of the examples on this site can be found in the Github repo's [examples](https://github.com/ryannhg/elm-spa/tree/main/examples) folder. -- This site -- Realworld example app -- User featured projects \ No newline at end of file +## Featured examples + +### Hello, world! + +[![Hello, world!](/content/images/01-hello-world.png)](/examples/01-hello-world) + +### Pages & routing + +[![Hello, world!](/content/images/01-hello-world.png)](/examples/01-hello-world) + +### Local storage + +[![Hello, world!](/content/images/01-hello-world.png)](/examples/01-hello-world) + +### User authentication + +[![Hello, world!](/content/images/01-hello-world.png)](/examples/01-hello-world) + +### Testing + +[![Hello, world!](/content/images/01-hello-world.png)](/examples/01-hello-world) + +### Working with NPM + +[![Hello, world!](/content/images/01-hello-world.png)](/examples/01-hello-world) \ No newline at end of file diff --git a/docs/public/content/guides/01-hello-world.md b/docs/public/content/examples/01-hello-world.md similarity index 100% rename from docs/public/content/guides/01-hello-world.md rename to docs/public/content/examples/01-hello-world.md diff --git a/docs/public/content/guides/02-pages.md b/docs/public/content/examples/02-pages.md similarity index 100% rename from docs/public/content/guides/02-pages.md rename to docs/public/content/examples/02-pages.md diff --git a/docs/public/content/examples/03-storage.md b/docs/public/content/examples/03-storage.md new file mode 100644 index 0000000..ef00db8 --- /dev/null +++ b/docs/public/content/examples/03-storage.md @@ -0,0 +1,3 @@ +# Storage + +> Coming soon! \ No newline at end of file diff --git a/docs/public/content/guides/03-user-auth.md b/docs/public/content/examples/04-authentication.md similarity index 96% rename from docs/public/content/guides/03-user-auth.md rename to docs/public/content/examples/04-authentication.md index 0619690..185ee84 100644 --- a/docs/public/content/guides/03-user-auth.md +++ b/docs/public/content/examples/04-authentication.md @@ -17,7 +17,7 @@ __Great news:__ This is exactly what we can do in __elm-spa__! ## Protected pages -At the end of the [pages docs](/docs/pages#pageprotected), we learned that there are also `protected` versions of every __page type__. +At the end of the [pages docs](/guide/pages#pageprotected), we learned that there are also `protected` versions of every __page type__. These protected pages have slightly different signatures: @@ -116,7 +116,7 @@ But before that code will work we need to take care of two things: ## Updating Shared.elm -If you haven't already ejected `Shared.elm`, you should move it from `.elm-spa/defaults` into your `src` folder. The [shared state](/docs/shared-state) docs cover this file in depth, but we'll provide all the code you'll need to change here. +If you haven't already ejected `Shared.elm`, you should move it from `.elm-spa/defaults` into your `src` folder. The [shared state](/guide/shared-state) docs cover this file in depth, but we'll provide all the code you'll need to change here. Let's change `Shared.Model` to keep track of a `Maybe User`, the value that can either be a user or nothing: @@ -382,4 +382,4 @@ Now everything is working! Visiting the `/sign-in` page and clicking "Sign In" s #### But wait... -When we refresh the page, the user is signed out... how can we keep them signed in after refresh? Sounds like a job for [local storage](/guides/local-storage)! +When we refresh the page, the user is signed out... how can we keep them signed in after refresh? Sounds like a job for [local storage](/examples/local-storage)! diff --git a/docs/public/content/examples/05-testing.md b/docs/public/content/examples/05-testing.md new file mode 100644 index 0000000..7766818 --- /dev/null +++ b/docs/public/content/examples/05-testing.md @@ -0,0 +1,3 @@ +# Testing + +> Coming soon! \ No newline at end of file diff --git a/docs/public/content/examples/06-npm.md b/docs/public/content/examples/06-npm.md new file mode 100644 index 0000000..6dd1bfa --- /dev/null +++ b/docs/public/content/examples/06-npm.md @@ -0,0 +1,3 @@ +# Working with NPM + +> Coming soon! \ No newline at end of file diff --git a/docs/public/content/docs.md b/docs/public/content/guide.md similarity index 96% rename from docs/public/content/docs.md rename to docs/public/content/guide.md index e12832e..23fec43 100644 --- a/docs/public/content/docs.md +++ b/docs/public/content/guide.md @@ -1,4 +1,4 @@ -# Docs +# Guide Welcome to __elm-spa__, a framework for building web applications with [Elm](https://elm-lang.org)! If you are new to Elm, you should check out [the official guide](https://guide.elm-lang.org), which @@ -68,4 +68,4 @@ Visit https://elm-spa.dev for more! __Ready for more?__ -Let's check out [the CLI](/docs/cli) to learn more about those five commands! +Let's check out [the CLI](/guide/cli) to learn more about those five commands! diff --git a/docs/public/content/docs/cli.md b/docs/public/content/guide/cli.md similarity index 77% rename from docs/public/content/docs/cli.md rename to docs/public/content/guide/cli.md index ad5a9cb..03e966b 100644 --- a/docs/public/content/docs/cli.md +++ b/docs/public/content/guide/cli.md @@ -10,9 +10,10 @@ This gave us the ability to run a few commands: 1. [__elm-spa new__](#elm-spa-new) - creates a new project 1. [__elm-spa server__](#elm-spa-server) - runs a dev server as you code -1. [__elm-spa watch__](#elm-spa-watch) - builds as you code -1. [__elm-spa build__](#elm-spa-build) - one-time production build 1. [__elm-spa add__](#elm-spa-add) - adds a page to an existing project +1. [__elm-spa build__](#elm-spa-build) - one-time production build +1. [__elm-spa gen__](#elm-spa-gen) - generates files, without elm make +1. [__elm-spa watch__](#elm-spa-watch) - generates files as you code What do these do? This section of the guide dives into more detail on each command! @@ -49,27 +50,6 @@ This will start a development server for your project at [http://localhost:1234] When we edit our code, `elm-spa server` automatically compiles your application. -## elm-spa watch - -If you want the automatic compilation on change, but don't need a HTTP server, you can use the `elm-spa watch` command: - -```terminal -elm-spa watch -``` - -This will automatically generate code and compile your Elm files on save, but without the server. This is a great command to combine __elm-spa__ with another tool like [Parcel](https://parceljs.org/elm.html). - - -## elm-spa build - -The `server` and `watch` commands are great for development, but for __production__, we'll want the `elm-spa build` command. - -```terminal -elm-spa build -``` - -This compiles your app into __an optimized and minified JS file__. This makes it great for serving your application in the real world! - ## elm-spa add @@ -103,3 +83,35 @@ elm-spa add /example static elm-spa add /example sandbox elm-spa add /example element ``` + +## elm-spa build + +The `server` and `watch` commands are great for development, but for __production__, we'll want the `elm-spa build` command. + +```terminal +elm-spa build +``` + +This compiles your app into __an optimized and minified JS file__. This makes it great for serving your application in the real world! + +## elm-spa gen + +If you are working with another dev server, you won't need the `.js` file generated by the `build` command. To only generate __elm-spa__ files, use the `elm-spa gen` command: + +```terminal +elm-spa gen +``` + +This will generate files in the `.elm-spa` folder, but allow your custom workflow to define it's own way of compiling Elm. This is a great command to combine __elm-spa__ with another tool like [Vite](/examples/05-npm) or [Parcel](https://parceljs.org/elm.html). + + +## elm-spa watch + +If you want the automatic code generation on change, but don't need elm make or an HTTP server, you can use the `elm-spa watch` command: + +```terminal +elm-spa watch +``` + +This will automatically generate code and compile your Elm files on save, but without the server. + diff --git a/docs/public/content/docs/pages.md b/docs/public/content/guide/pages.md similarity index 98% rename from docs/public/content/docs/pages.md rename to docs/public/content/guide/pages.md index 5e43ecb..f9cac1c 100644 --- a/docs/public/content/docs/pages.md +++ b/docs/public/content/guide/pages.md @@ -227,7 +227,7 @@ view : Model -> View Msg subscriptions : Model -> Sub Msg ``` -This `Effect Msg` value also allows support for folks using [elm-program-test](https://package.elm-lang.org/packages/avh4/elm-program-test/latest/), which requires users to define their own custom type on top of `Cmd Msg`. More about that in the [testing guide](/guides/06-testing) +This `Effect Msg` value also allows support for folks using [elm-program-test](https://package.elm-lang.org/packages/avh4/elm-program-test/latest/), which requires users to define their own custom type on top of `Cmd Msg`. More about that in the [testing guide](/examples/06-testing) ## Page.protected @@ -250,4 +250,4 @@ Page.protected.sandbox } ``` -When you are ready for user authentication, you can learn more about using `Page.protected` in the [authentication guide](/guides/04-authentication). +When you are ready for user authentication, you can learn more about using `Page.protected` in the [authentication guide](/examples/04-authentication). diff --git a/docs/public/content/docs/routing.md b/docs/public/content/guide/routing.md similarity index 98% rename from docs/public/content/docs/routing.md rename to docs/public/content/guide/routing.md index 4db86cd..476c4a3 100644 --- a/docs/public/content/docs/routing.md +++ b/docs/public/content/guide/routing.md @@ -16,7 +16,7 @@ In this section, we'll cover the different kinds of routes you'll find in every ## The homepage -`Home_.elm` is a reserved filename that handles requests to your homepage. The easiest way to add a new homepage is with the [`elm-spa add`](/docs/cli#elm-spa-add) covered in the CLI docs: +`Home_.elm` is a reserved filename that handles requests to your homepage. The easiest way to add a new homepage is with the [`elm-spa add`](/guide/cli#elm-spa-add) covered in the CLI docs: ```terminal elm-spa add / diff --git a/docs/public/content/docs/shared-state.md b/docs/public/content/guide/shared-state.md similarity index 92% rename from docs/public/content/docs/shared-state.md rename to docs/public/content/guide/shared-state.md index 5290ab8..cea5b7f 100644 --- a/docs/public/content/docs/shared-state.md +++ b/docs/public/content/guide/shared-state.md @@ -52,7 +52,7 @@ type alias User = } ``` -As we saw in the [pages guide](/docs/pages), this `Shared.Model` will be passed into every page– so we can check if `shared.user` has a value or not! +As we saw in the [pages guide](/guide/pages), this `Shared.Model` will be passed into every page– so we can check if `shared.user` has a value or not! ## Shared.init @@ -65,7 +65,7 @@ init flags req = The `init` function is called when your application loads for the first time. It takes in two inputs: - `Flags` - initial JS values passed in on startup. -- `Request` - the [Request](/docs/request) value with current URL information. +- `Request` - the [Request](/guide/request) value with current URL information. The `init` function returns the initial `Shared.Model`, as well as any side effect's you'd like to run (like initial HTTP requests, etc) diff --git a/docs/public/content/docs/url-requests.md b/docs/public/content/guide/url-requests.md similarity index 94% rename from docs/public/content/docs/url-requests.md rename to docs/public/content/guide/url-requests.md index 883c924..0577d28 100644 --- a/docs/public/content/docs/url-requests.md +++ b/docs/public/content/guide/url-requests.md @@ -12,7 +12,7 @@ This might be useful when you need to show the active link in your navbar, or na ## req.params -Every [dynamic route](/docs/routing#dynamic-routes) has parameters that you'll want to get access to. For [static routes](/docs/routing@static-routes), those parameters will be `()`: +Every [dynamic route](/guide/routing#dynamic-routes) has parameters that you'll want to get access to. For [static routes](/guide/routing@static-routes), those parameters will be `()`: URL | Request --- | --- diff --git a/docs/public/content/docs/views.md b/docs/public/content/guide/views.md similarity index 100% rename from docs/public/content/docs/views.md rename to docs/public/content/guide/views.md diff --git a/docs/public/content/guides.md b/docs/public/content/guides.md deleted file mode 100644 index 2c94ca5..0000000 --- a/docs/public/content/guides.md +++ /dev/null @@ -1,7 +0,0 @@ -# Guides - -Ready to get started with __elm-spa__? Me too! - -... - -Unfortunately, I haven't uploaded any guides yet... \ No newline at end of file diff --git a/docs/public/content/guides/04-storage.md b/docs/public/content/guides/04-storage.md deleted file mode 100644 index 5bbda60..0000000 --- a/docs/public/content/guides/04-storage.md +++ /dev/null @@ -1 +0,0 @@ -# Local storage \ No newline at end of file diff --git a/docs/public/content/guides/05-npm.md b/docs/public/content/guides/05-npm.md deleted file mode 100644 index a3af62a..0000000 --- a/docs/public/content/guides/05-npm.md +++ /dev/null @@ -1 +0,0 @@ -# Working with NPM \ No newline at end of file diff --git a/docs/public/style.css b/docs/public/style.css index 91635bc..82ed6c0 100644 --- a/docs/public/style.css +++ b/docs/public/style.css @@ -279,6 +279,15 @@ hr { border: 0; } transform: translate(50%, -25%); } +.markdown a img { + transition: transform 200ms ease-in-out, opacity 200ms ease-in-out; +} + +.markdown a img:hover { + transform: scale(1.05); + opacity: 0.75; +} + .bold { font-weight: var(--weight--bold); } diff --git a/docs/src/Domain/Index.elm b/docs/src/Domain/Index.elm index f979e96..2bfcb72 100644 --- a/docs/src/Domain/Index.elm +++ b/docs/src/Domain/Index.elm @@ -106,8 +106,7 @@ sections : Index -> List Section sections index = let sectionOrder = - [ "Docs" - , "Guides" + [ "Guide" , "Examples" ] @@ -143,6 +142,7 @@ sections index = index |> List.filter (.url >> (\url -> String.startsWith top.url url && url /= top.url)) |> toLabelUrls + |> List.sortBy .url |> toSection top ) |> List.sortBy diff --git a/docs/src/Pages/Guides/Section_.elm b/docs/src/Pages/Examples/Section_.elm similarity index 79% rename from docs/src/Pages/Guides/Section_.elm rename to docs/src/Pages/Examples/Section_.elm index 287b1a4..83bf974 100644 --- a/docs/src/Pages/Guides/Section_.elm +++ b/docs/src/Pages/Examples/Section_.elm @@ -1,4 +1,4 @@ -module Pages.Guides.Section_ exposing (Model, Msg, page) +module Pages.Examples.Section_ exposing (Model, Msg, page) import Page import Request diff --git a/docs/src/Pages/Docs.elm b/docs/src/Pages/Guide.elm similarity index 82% rename from docs/src/Pages/Docs.elm rename to docs/src/Pages/Guide.elm index 96f4bbf..b3f0d01 100644 --- a/docs/src/Pages/Docs.elm +++ b/docs/src/Pages/Guide.elm @@ -1,4 +1,4 @@ -module Pages.Docs exposing (Model, Msg, page) +module Pages.Guide exposing (Model, Msg, page) import Page import Request diff --git a/docs/src/Pages/Docs/Section_.elm b/docs/src/Pages/Guide/Section_.elm similarity index 79% rename from docs/src/Pages/Docs/Section_.elm rename to docs/src/Pages/Guide/Section_.elm index cd3b39b..53e3cd0 100644 --- a/docs/src/Pages/Docs/Section_.elm +++ b/docs/src/Pages/Guide/Section_.elm @@ -1,4 +1,4 @@ -module Pages.Docs.Section_ exposing (Model, Msg, page) +module Pages.Guide.Section_ exposing (Model, Msg, page) import Page import Request diff --git a/docs/src/Pages/Guides.elm b/docs/src/Pages/Guides.elm deleted file mode 100644 index b3bc528..0000000 --- a/docs/src/Pages/Guides.elm +++ /dev/null @@ -1,19 +0,0 @@ -module Pages.Guides exposing (Model, Msg, page) - -import Page -import Request -import Shared -import UI.Docs - - -page : Shared.Model -> Request.With params -> Page.With Model Msg -page = - UI.Docs.page - - -type alias Model = - UI.Docs.Model - - -type alias Msg = - UI.Docs.Msg diff --git a/docs/src/Pages/NotFound.elm b/docs/src/Pages/NotFound.elm index efa59f2..e8dd22d 100644 --- a/docs/src/Pages/NotFound.elm +++ b/docs/src/Pages/NotFound.elm @@ -32,6 +32,6 @@ view = { title = "404" , description = "that page wasn't found." } - , UI.markdown { withHeaderLinks = False } "### Well, that's a shame...\n\nHow about the [homepage?](/)" + , UI.markdown { withHeaderLinks = False } "## But that's alright.\n\nThere's always [the homepage](/)!" ] } diff --git a/docs/src/UI/Layout.elm b/docs/src/UI/Layout.elm index 810e33c..6f44429 100644 --- a/docs/src/UI/Layout.elm +++ b/docs/src/UI/Layout.elm @@ -125,10 +125,23 @@ navbar { onMsg, model, shared, url } = let navLink : { text : String, route : Route } -> Html msg navLink options = + let + href : String + href = + Route.toHref options.route + in Html.a [ Attr.class "link" - , Attr.href (Route.toHref options.route) - , Attr.classList [ ( "bold text-blue", String.startsWith (Route.toHref options.route) url.path ) ] + , Attr.href href + , Attr.classList + [ ( "bold text-blue" + , if href == "/" then + href == url.path + + else + String.startsWith href url.path + ) + ] ] [ Html.text options.text ] in @@ -138,8 +151,8 @@ navbar { onMsg, model, shared, url } = [ Html.div [ Attr.class "row align-center gap-lg" ] [ Html.a [ Attr.class "header__logo", Attr.href "/" ] [ UI.logo ] , Html.nav [ Attr.class "row gap-md hidden-mobile pad-left-xs" ] - [ navLink { text = "docs", route = Route.Docs } - , navLink { text = "guides ", route = Route.Guides } + [ navLink { text = "about", route = Route.Home_ } + , navLink { text = "guide", route = Route.Guide } , navLink { text = "examples", route = Route.Examples } ] ]