Build a site
Every page starts as a Markdown file. atlas reads the files in content/, renders each one through a template and writes the result to a folder you can upload anywhere. This page walks the whole trip, from the first file to the live site.
atlas new guide/install.md
Write the pages
The folder a file sits in becomes its path. content/index.md is the home page, and content/guide/install.md is /guide/install/. Rename a file and its address changes with it, so move pages early rather than late.
The block at the top of each file is its front matter. atlas reads the title, the date and the order from there, hands the rest to the template, and leaves anything it does not know alone. A file whose name starts with an underscore is a partial: it is read, but it never becomes a page of its own.
title = "Field notes"
base = "https://notes.example"
out = "_site"
drafts = false
[build]
clean = true
minify = true
sitemap = trueLine 4 keeps drafts out of the build. Lines 8 and 9 shrink the output and write a sitemap.
Set the build options
Running atlas build reads atlas.toml, renders every page in parallel and writes the result. Each setting in the file also has a flag, and the flag wins, which is what makes one command behave differently in a terminal and on a build server.
| Option | Default | What it does |
|---|---|---|
| --out | _site | The folder the built pages land in. |
| --base | from atlas.toml | The root address, used for links and the sitemap. |
| --drafts | off | Builds the pages marked as drafts as well. |
| --clean | on | Empties the output folder before it writes. |
| --watch | off | Rebuilds what changed on every save and reloads the open page. |
Put it online
The output is plain files, so any host that serves a folder will do. atlas checks every internal link before it finishes, and a broken one fails the build rather than reaching a reader.
- Build the site
- Read the report
- Upload the folder
The report names every page it wrote, every link it could not find and the time each step took. Keep it: when a build slows down, the earlier report says which step grew.
Questions
Why is the first build slower than the rest?
The first run reads every file and builds the link index. After that a watch run rebuilds only the pages that changed, which is why the second build of a thousand pages takes about two seconds.
Can I run atlas on a build server?
Yes. It is one binary with no runtime of its own, so a build step is atlas build --base $SITE_URL and nothing else. It returns a non-zero code when a link breaks.
Where do the built files go?
Into _site, or wherever --out points. The folder is emptied first unless you turn clean off.