mirror of
https://github.com/dillonkearns/elm-pages.git
synced 2024-09-11 09:05:28 +03:00
50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# 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`
|