srid/ema
1
1
Fork 0
mirror of https://github.com/srid/ema.git synced 2024-11-22 21:52:56 +03:00
Code Issues Projects Releases Wiki Activity

doc: misc

Browse Source
This commit is contained in:
Sridhar Ratnakumar 2022-06-22 10:38:56 -04:00
parent da5b29f03c
commit bc769acf81
3 changed files with 11 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -2,7 +2,7 @@
## 0.8.0.0 (Unreleased)
This releases brings a significant rewrite of Ema. If you choose to upgrade your apps from 0.6, see https://ema.srid.ca/guide/upgrade for guidance.
This releases brings a significant rewrite of Ema. If you choose to upgrade your apps from 0.6, see https://ema.srid.ca/howto/upgrade for guidance.
- GHC 9.0 support
- Better handling of URL anchors (#83; #87)

6
docs/index.md
View File

@ -13,7 +13,7 @@ page:
[Ema](https://github.com/srid/ema) is a next-gen [**Haskell**](https://www.srid.ca/haskell) library for building [jamstack-style](https://jamstack.org/) static sites. An Ema site is *change-aware*; in addition to good ol' static site generation, Ema provides a live server supporting **fast hot-reload** in the browser, on code *or* data change.
{.text-gray-600}
The ultimate goal of ema is to facilitate creating with ease your own [neuron](https://neuron.zettel.page/), or just about any app that creates a browser view of arbitrarily changing data (on disk, database, or whatever). Ema is designed to facilitate creation of apps whose data is normally *edited* via traditional mechanisms (eg: text editor) but *rendered* as a delightful web page - so as to provide an economical read-only view of your data on desktop & mobile. A classic static site just happens one of the kind of such apps.
The ultimate goal of ema is to facilitate creating with ease your own [neuron](https://neuron.zettel.page/),[^emanote] or just about any app that creates a browser view of arbitrarily changing data (on disk, database, or whatever). Ema is designed to facilitate creation of apps whose data is normally *edited* via traditional mechanisms (eg: text editor) but *rendered* as a delightful web page - so as to provide an economical read-only view of your data on desktop & mobile. A classic static site is just one type of such [*kind*]{title="See what we did there?"} of apps.
:::{.my-8}
* [[start]]
@ -27,4 +27,6 @@ The ultimate goal of ema is to facilitate creating with ease your own [neuron](h
<source src="static/ema-demo.mp4" />
<p>Your browser doesn't support HTML5 video. Here is a <a href="static/ema-demo.mp4">link to the video</a> instead.</p>
</video>
:::
:::
[^emanote]: This ultimate goal was already realized in regards to neuron; see [Emanote](https://emanote.srid.ca/), which is built on top of Ema.

10
docs/start/tutorial.md
View File

@ -1,9 +1,11 @@
# Tutorial
Make sure that you have have followed [[start|the previous section]] in order to have the [template repo](https://github.com/srid/ema-template) checked out and running locally. Here, **our goal** is to replace the source code of the template repo and write a basic site from scratch.
We assume that you have followed [[start|the previous section]] to have the [template repo](https://github.com/srid/ema-template) checked out and running locally. Here, **our goal** is to replace the source of that template repo and write a basic site from scratch.
## Hello World
We will start with "hello world" Ema app.
1. Follow the template repo's [README](https://github.com/srid/ema-template#getting-started) and have it open in Visual Studio Code while running the dev server. Your website should be viewable at <http://localhost:9001/>
1. Open `src/Main.hs`
1. Delete everything in it, and replace it with the following
@ -30,11 +32,11 @@ main :: IO ()
main = void $ Ema.runSite @Route ()
```
The above is the *minimum* amount of code necessary to run an Ema site. Notice that as you replace and save this file, your browser (which is at <http://locahost:9001>) will [[hot-reload|hot reload]] to display "Hello, Ema". Congratulations, you just created your first website!
The above is the *minimum* amount of code necessary to run an Ema site. Notice that as you replace and save this file, your browser (which is pointing at <http://locahost:9001>) will [[hot-reload|hot reload]] to display "Hello, Ema". Congratulations, you just created your first website!
## Expanding on Hello World
The above was a trivial static site with *one* page only. Let's say we want to add a second page. And we might as well add more content than "Hello, Ema". Let's do that next. The first step is define the [[routes|route]] type that corresponds to our site's two pages. Replace the existing `Route` type with the following:
The above was a trivial static site with *one* page only. And there's nothing, umm, dynamic about it. Let's say we want to add a second page. And we might as well add more (dynamic; ie., time-varying) content than "Hello, Ema". Let's do that next. The first step is define the [[routes|route]] type that corresponds to our site's two pages. Replace the existing `Route` type with the following:
```haskell
data Route
@ -51,7 +53,7 @@ data Route
Note that we derive `IsRoute` generically (via SOP instances) which in turn gives us free route encoding and decoding. Here, `Route_Foo` encodes to `/foo.html`. TODO: Link to guide parts
:::
Next, let's define a [[model|model]]. A model will hold the state of our website used to render its HTML. To demonstrate that this model can change over time, we will put the current in it:
Next, let's define a [[model|model]]. A model will hold the state of our website used to render its HTML. To demonstrate that this model can change over time, we will put the current time in it:
```haskell
import Data.Time