roxy-docs/in/pages/quick-start.md

85 lines
2.2 KiB
Markdown
Raw Normal View History

2024-02-20 11:42:49 +00:00
{% extends "../../layouts/topic.tera" %}
{% block content %}
## Your first page
We're going to speedrun making your first site with Roxy.
Create a new directory for the project.
```bash
mkdir my-new-site
cd my-new-site
```
Create two direcroties in your new project, one for input and one for output.
```bash
mkdir {input,output}
```
Create a new file with some markdown content in `input` to add a page.
```bash
touch input/index.md
cat << EOF > input/index.md
# Hello, world!
This is my new site!
EOF
```
Build the site with `roxy-cli`.
```bash
roxy-cli ./input/ ./output/
```
Host the content and view it.
```bash
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.
```bash
mkdir layouts
touch layouts/base.tera
```
Let's add some boilerplate HTML to `layouts/base.tera`
```html
<!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>{% raw -%}
{% block body %}{% endblock body %}{% endraw %}
</body>
</html>
```
The `{% raw %}{% ... %}{% endraw %}` bit is the [Tera templating language](https://keats.github.io/tera/docs/) (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.
```md
{%- raw -%}{% extends "../layouts/base.tera" %}
{% block body %}{% endraw -%}
# Hello, world!
This is my new site!{% raw -%}
{% endblock body %}{% endraw -%}
```
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](https://keats.github.io/tera/docs/).
{% endblock content %}