README

# Kivy.org Website (https://www.kivy.org)

## Folder structure
- `configs` : contains the configurations needed to build the page templates via the **build** tool (during development and also distribution).
- `content` : This folder will be copied as-is to the website distribution (`dist`) during **build**. _Please make sure that everything included in this folder is expected to be publicily accessibile via kivy.org_
- `templates` : All the HTML templates needed to build the Kivy website are here.
- `tools`: Contains `build.py`, which is needed in order to build the website.


## How it works the page generation via templates?

The **build tool** (`tools/build.py`) uses the `config/config.json` file in order to know what and how pages should be built.

As you can see, in `config/config.json` there are multiple pages defined, and each page have its own `template` and an `env`.

### Yeah, but in `templates/index.html`, there's a `[[ include "components/header.html" ]]` what that does mean? And how we should use the `env` ?

The **build tool** uses [Renoir](https://github.com/emmett-framework/renoir) under the hood as a templating engine, is easy, production-ready and have a quite complete [documentation](https://github.com/emmett-framework/renoir/blob/master/docs/quickstart.md).

`env` should contain all the variables that need to be accessed during the page generation.

As an example, with the following configuration:
```
...
{
    "template": "index.html",
    "env": {
        "name": "Kivy"
    }
}
...
```
And the following snippet in `index.html`
```
<p>Hi, [[ =name ]]</p>
```

Will produce the following output, when the template has been built:

```
<p>Hello, Kivy</p>
```

## And how about the styling (CSS)?

Writing CSS code from scratch could be boring, stressful and sometimes a pain to mantain.

[TailwindCSS](https://github.com/tailwindlabs/tailwindcss) fills this gap, marking itself as a utility-first CSS framework for rapidly building custom user interfaces.

Also TailwindCSS comes with an extensive documentation, and offers a lot of examples: [Getting Started with Tailwind CSS](https://tailwindcss.com/docs)

## Quick start:

### First-time setup
- Clone the `kivy-website` repository and move into the `kivy-website` folder
    ```bash
    git clone https://github.com/kivy/kivy-website.git
    cd kivy-website
    ```
-  Install `node` requirements (`tailwindcss`)
    ```bash
    npm install
    ```
- Install the required `python` deps to build the website templates. (a virtualenv is recommended)
    ```bash
    pip install -r requirements.txt
    ```

## Building the website (output is placed in the `dist` folder)

### Development mode

Both **tailwindcss** and the **build tool** come with autoreload option, in order to speed-up the website development.

```bash
npm run develop
```

```bash
python tools/build.py --watch
```

### Building for production

```bash
npm run build
```

```bash
python tools/build.py
```