Skip to content

Commit 7fdfdc3

Browse files
mhanbergmhanberg
committed
feat: improve readme in generated project
1 parent 43b3a0a commit 7fdfdc3

1 file changed

Lines changed: 10 additions & 181 deletions

File tree

‎priv/templates/primary/README.md‎

Lines changed: 10 additions & 181 deletions
Original file line numberDiff line numberDiff line change
@@ -2,192 +2,21 @@
22

33
## Getting Started
44

5-
The examples in the README use the [Temple](https://github.com/mhanberg/temple) library to demonstrate that Tableau can be used with any markup language of your choice. You could easily use the builtin EEx, or use HEEx, Surface, or HAML.
5+
Once you bootstrap and enter your project, fetch your dependencies and start the build server. The server is available at http://localhost:4999
66

7-
### Layouts
7+
```shell
8+
cd <%= @app %>
9+
mix deps.get
810

9-
Layouts are modules that use the `use Tableau.Layout` macro.
10-
11-
Layouts have access to the `@site` and `@page` assign.
12-
13-
The `@site` assign contains your site's config.
14-
15-
The `@page` assign contains all the options passed to the `use Tableau.Page` macro.
16-
17-
```elixir
18-
defmodule MySite.RootLayout do
19-
use Tableau.Layout
20-
21-
import Temple
22-
23-
def template(assigns) do
24-
temple do
25-
"<!DOCTYPE html>"
26-
27-
html lang: "en" do
28-
head do
29-
meta charset: "utf-8"
30-
meta http_equiv: "X-UA-Compatible", content: "IE=edge"
31-
meta name: "viewport", content: "width=device-width, initial-scale=1.0"
32-
33-
title do
34-
@page.some_assign
35-
end
36-
37-
link rel: "stylesheet", href: "/css/site.css"
38-
end
39-
40-
body class: "font-sans" do
41-
main class: "container mx-auto px-2" do
42-
div class: "border-4 border-green-500" do
43-
a class: "text-blue-500 hover:underline", href: "/about" do
44-
"About"
45-
end
46-
47-
a class: "text-blue-500 hover:underline", href: "/posts" do
48-
"Posts"
49-
end
50-
51-
render @inner_content
52-
end
53-
end
54-
end
55-
56-
if Mix.env() == :dev do
57-
c &Tableau.live_reload/1
58-
end
59-
end
60-
end
61-
end
62-
end
63-
```
64-
65-
#### Page
66-
67-
Pages are modules that use the `use Tableau.Page` macro.
68-
69-
Required options:
70-
71-
* `:layout` - which layout module to use.
72-
* `:permalink` - the permalink of the page
73-
74-
Any remaining options are arbitrary and will be available under the `@page` assign available to layout and page templates.
75-
76-
```elixir
77-
defmodule MySite.AboutPage do
78-
use Tableau.Page,
79-
layout: MySite.RootLayout,
80-
permalink: "/about",
81-
some_assign: "foo"
82-
83-
import Temple
84-
85-
def template(assigns) do
86-
temple do
87-
span class: "text-red-500 font-bold" do
88-
"i'm a super cool and smart!"
89-
end
90-
end
91-
end
92-
end
93-
```
94-
95-
### Live Reloading
96-
97-
You can specify a set of directories/files to watch for changes, and the browser will automatically refresh.
98-
99-
```elixir
100-
# config/config.exs
101-
import Config
102-
103-
config :tableau, :reloader,
104-
patterns: [
105-
~r"lib/layouts/.*.ex",
106-
~r"lib/pages/.*.ex",
107-
~r"lib/components.ex",
108-
~r"_site/.*.css"
109-
]
110-
```
111-
112-
All you need to do is render the `Tableau.live_reload/1` component right after your `body` tag.
113-
114-
```elixir
115-
# lib/layouts/app.ex
116-
117-
defmodule YourApp.Layouts.App do
118-
use Tableau.Layout
119-
120-
import Temple
121-
122-
def template(assigns) do
123-
temple do
124-
"<!DOCTYPE html>"
125-
126-
html lang: "en" do
127-
head do
128-
meta charset: "utf-8"
129-
meta http_equiv: "X-UA-Compatible", content: "IE=edge"
130-
meta name: "viewport", content: "width=device-width, initial-scale=1.0"
131-
132-
link rel: "stylesheet", href: "/css/site.css"
133-
end
134-
135-
body class: "font-sans" do
136-
main class: "container mx-auto px-2" do
137-
render(@inner_content)
138-
end
139-
end
140-
141-
if Mix.env() == :dev do
142-
c &Tableau.live_reload/1
143-
end
144-
end
145-
end
146-
end
147-
end
148-
```
149-
150-
151-
### JS/CSS
152-
153-
You can arbitrarily start other build tools as "watchers". This is inspired by the way Phoenix does it.
154-
155-
```elixir
156-
# config/config.exs
157-
158-
import Config
159-
160-
config :tableau, :assets,
161-
npx: [
162-
"tailwindcss",
163-
"-o",
164-
"_site/css/site.css",
165-
"--watch"
166-
]
167-
168-
# or if you are using a package similar to the TailwindCSS hex package
169-
170-
config :tableau, :assets, tailwind: {Tailwind, :install_and_run, [:default, ~w(--watch)]}
171-
172-
import_config "#{config_env()}.exs"
11+
mix tableau.server
17312
```
17413

175-
This will start a long running process that will independently build your CSS as it sees files change.
176-
177-
These are started automatically when you run `mix tableau.server`.
178-
179-
### Static Assets
14+
## Production Builds
18015

181-
Other static assets can be copied into the "out" directory by placing them in an `extra` directory in the root of your project.
16+
To build for production, run the `mix build` alias to build your site and compile any assets (depends on what asset you chose when generating your site).
18217

183-
This directory can be configured.
18+
Running your build with `MIX_ENV=prod` is important so that the live reload JS script is not loaded, and also allows you to configure your app differently in dev vs prod, like showing future posts in dev, but not in prod.
18419

185-
```elixir
186-
config :tableau, :config,
187-
include_dir: "static"
20+
```shell
21+
MIX_ENV=prod mix build
18822
```
189-
190-
### Development
191-
192-
The dev server can be started with `mix tableau.server`. On file change, a browser reload will be triggered and the page your requesting will be re-built during the request.
193-

0 commit comments

Comments
 (0)