TutorialBuild a blog

Unit 1: Setup

Install Douze, create the folder of the blog, write a first page and run the development server.

In this unit you will:

  • install Douze and check that it runs,
  • create the folder of the blog and its first page,
  • run the development server and see the page reload as you edit it,
  • build the site and look at what Douze writes.

Step 1: install DouzeLink to this heading

Run the install script of your system:

macOS and LinuxLink to this heading

curl -fsSL https://raw.githubusercontent.com/sebastienros/douze/main/install.sh | sh -s -- --preview

Windows (PowerShell)Link to this heading

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sebastienros/douze/main/install.ps1))) -Preview

Open a new terminal, so that it sees the updated PATH, and check the installation:

douze --version

It prints the installed version, such as 1.0.0-preview.36. If your shell does not find douze, see Installation for other ways to install it and for troubleshooting.

Step 2: create the site folderLink to this heading

A Douze site is a folder. Create one for the blog, with a _content folder inside it:

mkdir my-blog
cd my-blog
mkdir _content

_content holds the pages of the site and every other file to publish. Douze turns each page into a file of the output folder, at the same place: _content/index.md becomes the home page.

Step 3: write the home pageLink to this heading

Create _content/index.md with this content:

_content/index.md
---
title: My blog
---
# Welcome to my blog

This is where I write about learning Douze.

The block between the two --- lines is the page's front matter: YAML data about the page. Here it gives the page a title, which you will use in unit 2. The rest is Markdown.

Step 4: start the development serverLink to this heading

From the my-blog folder, run:

douze serve

Douze builds the site, then serves it and watches your files:

✓ folder-data       0 files    0.00 s     0.00 s work
✓ pages             1 file     0.00 s     0.00 s work
✓ permalink         1 file     0.00 s     0.00 s work
✓ collections       1 file     0.00 s     0.00 s work
✓ paginate          1 file     0.00 s     0.00 s work
✓ render            1 file     0.00 s     0.00 s work
✓ markdown          1 file     0.00 s     0.00 s work
✓ layout            1 file     0.00 s     0.00 s work
✓ write             1 file     0.00 s     0.00 s work
Build succeeded: 9 steps, 1 file written in 0.03 s, 9 units executed
Serving _site at http://localhost:8080/
Watching . for changes (Ctrl+C to stop)

Each line is a step of the build: reading data files, front matter, computing output paths, rendering Liquid and Markdown, applying layouts, writing files. You will meet each of them in this tutorial, and change them in unit 6.

Open http://localhost:8080/ in your browser. You see the heading "Welcome to my blog" and the paragraph under it.

Now edit _content/index.md: change the paragraph, and save. The terminal prints one line for the rebuild, and the page in the browser reloads by itself:

_content/index.md changed: 1 file written in 0.01 s, 8 units executed, 1 cached

Keep douze serve running while you follow the tutorial: every page you add or change shows up in the browser when you save it.

Step 5: look at the outputLink to this heading

Douze writes the site to the _site folder. Open _site/index.html in your editor:

<h1>Welcome to my blog</h1>
<p>This is where I write about learning Douze.</p>

That is the whole page: the HTML of your Markdown, and nothing else yet. There is no <html> or <head>, because the page has no layout. You will add one in unit 4.

When the development server serves a page, it adds a small live reload script to it. The file in _site does not have it: what is in _site is what you publish.

You can also build the site once, without a server, by running douze alone (douze build does the same). Stop the server with Ctrl+C first, or run it from another terminal:

douze

Next to _site, Douze created a .douze folder. It is the build cache: Douze stores the result of each piece of work, and the next build reuses what did not change. That is why a second build without changes says 0 units executed. You can delete it at any time, or build without it with douze --no-cache. See Cache and incremental builds.

Step 6: ignore the generated foldersLink to this heading

If you keep the blog in Git (you will need it to deploy in unit 6), the output and the cache should stay out of it. Create a .gitignore file in the my-blog folder:

.gitignore
_site/
.douze/

Then create the repository:

git init
git add .
git commit -m "My blog"
Answers
  1. _content. Without it, the site folder itself holds the pages.
  2. It serves the site on http://localhost:8080/, rebuilds it when a file changes, and reloads the pages in the browser.
  3. _site, the output, and .douze, the build cache.

NextLink to this heading

In unit 2, you will add pages, blog posts and links between them, and use front matter in templates.

Esc to close