README.md 2.72 KB
Newer Older
1 2
# Boop! – a simple "low-tech" static site generator, for fun.

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
## Installation

In this guide, we assume you are using Linux.

First, you should clone the Boop! repository and install its dependencies.
Boop! requires Python 3.6 to work (mainly because of our use of the `f-strings`).

```console
$ git clone https://framagit.org/marien.fressinaud/boop.git
$ cd boop
$ pip3 install -r requirements.txt
$ cd ..
```

Then, add the path to your `.bashrc`:

```console
$ echo export PATH="$(pwd)/boop:\$PATH" >> ~/.bashrc
```

And source it so it considers the change:

```console
$ source ~/.bashrc
```

29 30
## Usage

31 32 33 34 35
First, create a project directory:

```console
$ mkdir my-website && cd my-website
```
36

37
Create a `./content` folder and execute the Boop! command:
38 39 40 41

```console
$ mkdir content
$ echo '<h1>Welcome!</h1>' > content/index.html
42
$ boop.py
43 44 45 46 47 48 49 50 51 52 53 54 55
Boop!
```

Now, you should have your "production-ready" website under a `./output` folder.

For example, if your website consists in a single `index.html` page, you should
obtain the following structure:

```console
$ tree
.
├── content
│   └── index.html
56 57
└── output
    └── index.html
58 59
```

60
Boop! basically just copied `content` files under a `output` directory. But it
61 62 63 64 65 66 67 68 69
can convert Markdown files in HTML too. For that, you'll need a template file
for articles:

```console
$ mkdir theme
$ echo '<html><body>{{ ARTICLE_CONTENT }}</body></html' > theme/article.html
```

Then, you can create your Markdown file as you did with the HTML one:
70 71 72 73 74

```console
$ echo '# Welcome!' > content/markdown-index.md
$ boop.py
$ echo output/markdown-index.html
75
<html><body><h1>Welcome!</h1></body></html>
76
```
77

78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
You can define meta variables in the Markdown file which will be accessible
then in the template. Variables are uppercased and prepended by `ARTICLE_`. For
example, for the following Markdown file:

```markdown
---
title: Welcome!
author: Marien
---

This is my article.
```

And the HTML template:

```html
<html>
    <head>
        <title>{{ ARTICLE_TITLE }}</title>
    </head>
    <body>
        <h1>{{ ARTICLE_TITLE }}</h1>
        <p>By {{ ARTICLE_AUTHOR }}</p>

        {{ ARTICLE_CONTENT }}
    </body>
</html>
```

It will produce the following file:

```html
<html>
    <head>
        <title>Welcome!</title>
    </head>
    <body>
        <h1>Welcome!</h1>
        <p>By Marien</p>

        <p>This is my article.</p>
    </body>
</html>
```

For now, you can use any valid Python expression between `{{ }}`, you have
access to the variables defined in the meta header, the Python builtin
functions and the `datetime` module.

127 128 129 130 131 132 133 134
## Tests

There are some tests (i.e. doctests) that can be run to check that everything
works smoothly. They can be executed with:

```console
$ python3 -m doctest -v boop.py
```