docs/content/start/first-site.md (2795B)
1 +++
2 title = "Your first site"
3 description = "From an empty directory to a page on screen"
4 weight = 20
5 toc = true
6 +++
7
8 ```bash
9 sqzass init mysite
10 sqzass serve -i mysite
11 ```
12
13 That is the whole thing. `init` writes three files, `serve` puts them on
14 <http://127.0.0.1:3000>, and there is no fourth step.
15
16 ## What it wrote
17
18 ```
19 mysite/
20 ├── sqzass.toml
21 ├── content/
22 │ └── _index.md
23 └── templates/
24 └── page.html
25 ```
26
27 Three files, because a scaffold you have to delete half of is not a head start.
28 There is no `.gitignore` you did not ask for, no example blog post, and no
29 directory sqzass expects to own.
30
31 `init` refuses to run in a directory that already has a `sqzass.toml`, so it
32 cannot half-overwrite a site you already have.
33
34 ## sqzass.toml
35
36 Two keys. Everything else has a default, and a key you leave out behaves as if
37 it were set to that default.
38
39 ```toml
40 title = "mysite"
41 base_url = "https://example.com"
42 ```
43
44 ## content/_index.md
45
46 The front page. Front matter is TOML between `+++` fences, and `title` is the
47 only field you must supply.
48
49 ```markdown
50 +++
51 title = "mysite"
52 +++
53
54 Hello.
55 ```
56
57 ## templates/page.html
58
59 `page.content` is already HTML, so it needs `| safe` — templates escape by
60 default, and that default is what keeps a stray `<` in your prose from becoming
61 markup.
62
63 ```html
64 <!doctype html>
65 <html lang="{{ page.language }}">
66 <head>
67 <meta charset="utf-8">
68 <title>{{ page.title }}</title>
69 {%- if site.highlight_css %}
70 <link rel="stylesheet" href="{{ site.highlight_css }}">
71 {%- endif %}
72 </head>
73 <body>{{ page.content | safe }}</body>
74 </html>
75 ```
76
77 The `site.highlight_css` line is the stylesheet the build generates from your
78 syntax themes. Leave it out and code blocks come out unstyled.
79
80 ## Building it
81
82 ```bash
83 sqzass build -i mysite
84 ```
85
86 The output lands in `mysite/public`. Every page is written as
87 `<path>/index.html`, never `<path>.html`, so the URL is `/about/` and not
88 `/about.html` — see [Writing content](@/content/_index.md) for why that matters
89 on a host with no rewrite rules. A sitemap and a `robots.txt` come out too.
90
91 ## Working on it
92
93 `sqzass serve` rebuilds when a file changes. Nothing is written to `public/`
94 while it runs, so a rebuilding site never serves a half-written file. The page
95 reloads itself; a change that only touched CSS swaps the stylesheet in place
96 and keeps your scroll position.
97
98 > [!NOTE]
99 > The dev server is a development tool. It does no caching, no compression and
100 > no access control. Serve the built directory with a real server in production.
101
102 ## What to add next
103
104 A second page is a second file. `content/about.md` becomes `/about/`, and
105 `content/guide/_index.md` starts a section that collects everything beside it.
106 [Front matter](@/content/front-matter.md) lists the fields a page can carry.