Quick start

Your first page

We're going to speedrun making your first site with Roxy.

Create a new directory for the project.

mkdir my-new-site
cd my-new-site

Create two direcroties in your new project, one for input and one for output.

mkdir {input,output}

Create a new file with some markdown content in input to add a page.

touch input/index.md
cat << EOF > input/index.md
# Hello, world!
This is my new site!
EOF

Build the site with roxy_cli.

roxy_cli ./input/ ./output/

Host the content and view it.

cd output
python3 -m http.server # visit localhost:8000 with your browser

Adding a layout

At the top level of your project, create a new directory and add a new file. We don't want this being built with the rest of the content.

mkdir layouts
touch layouts/base.tera

Let's add some boilerplate HTML to layouts/base.tera

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>My New Site!</title>
  </head>
  <body>
{% block body %}
{% endblock body %}
  </body>
</html>

The {% ... %} bit is the Tera templating language (it's meant to look like Jinja, if you're familiar with that). This syntax is how we do fun templating things -- in this case, we're creating a block that other pages can fill later.

Let's go back to input/index.md and use this layout.


{%  extends "../layouts/base.tera" %}

{% block body %}
# Hello, world!
This is my new site!
{% endblock body %}

Build the site again, host it, and look at the result. There should be a title that says "My New Site!" and the content should be the same. Check out the output folder to get an idea of how Roxy builds and structures files.

Tera has many more features to explore, so I'd highly recommend looking at the documentation.