Alpha Instructions

What to expect

The API is not yet stable, and there will be breaking changes between now and the public 2.0 release.

There may be some remaining bugs, but overall the current alpha appears to be relatively stable.

There isn't a lot of documentation beyond the examples folder and this document right now. Part of the alpha process will be getting the documentation ready, and changing APIs wherever things appear to be confusing or have API improvement opportunities.

Feedback and documentation improvements are very welcome.

Installation

The alpha isn't published on npm, so the two ways to set it up are by working directly in this git repository, or by pulling this repository down as a git submodule.

If you work directly within this repository, you can copy-paste one of the examples/ projects and tweak that. Then you can pull in the latest code to tweak it.

To install it as a git submodule, you can do git submodule add https://github.com/dillonkearns/elm-pages && cd elm-pages && git checkout static-files. Then you need to install the NPM pacakge from the top-level project with npm install ./elm-pages. Then make sure you include ./elm-pages/src in your source-directories in your elm.json.

Special files

Document.elm - defines the types for your applications view. Can expose any type called Document msg (must have exactly one type variable)
Shared.elm must expose
- template : SharedTemplate Msg Model StaticData msg
- Msg
- Model
- SharedMsg (todo - this needs to be documented better. Consider whether there could be an easier way to wire this in for users, too)
Site.elm - must expose
- config : SiteConfig StaticData
static/index.js - same as previous beta-index.js
static/style.css - same as previous beta-style.css

Available generated code

Route.elm - lets you refer to a Route, and turn it into a path
- Every variant in Route has a record of RouteParams, which match the type alias RouteParams = { ... } in the corresponding Page Template
- Each Route has RouteParams - some of them empty, some of them non-empty - each param is a String, and the field key for each param corresponds to a dynamic segment (ending in _) in the Page Template's module name. For example, Template.Slide.Number_ has a single route param, so it has type alias RouteParams = { number : String }
- You can link or navigate to a Route programatically with firstSlide = Route.Slide__Number_ { number = "1" }
- You can turn it to a String with "/" + (Route.routeToPath firstSlide |> String.join "/")

Commands

Run a dev server - elm-pages dev
Generate scaffolding for a new Page Template - elm-pages add Slide.Number_
Run a build - elm-pages build

2.7 KiB Raw Permalink Blame History