Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
So GitHub knows how to display it. Fixes #154
- Loading branch information
Showing
1 changed file
with
88 additions
and
88 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,89 +1,89 @@ | ||
| # 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 publicly accessible 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 do we generate the page from templates? | ||
| The **build tool** (`tools/build.py`) uses the `config/config.json` file in order to know which pages should be built and how to build them. | ||
| Multiple pages are defined in `config/config.json`, and each page has its own `template` and `env`. | ||
| ### But in `templates/index.html`, there's an `[[ include "components/header.html" ]]`. What that does mean? And how we should use `env`? | ||
| The **build tool** uses [Renoir](https://github.com/emmett-framework/renoir) under the hood as a templating engine. Renoir is easy, production-ready and has 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: | ||
| ```json | ||
| ... | ||
| { | ||
| "template": "index.html", | ||
| "env": { | ||
| "name": "Kivy" | ||
| } | ||
| } | ||
| ... | ||
| ``` | ||
| And the following snippet in `index.html` | ||
| ```html | ||
| <p>Hi, [[ =name ]]</p> | ||
| ``` | ||
| Will produce the following output, when the template has been built: | ||
| ```html | ||
| <p>Hello, Kivy</p> | ||
| ``` | ||
| ## How about the styling (CSS)? | ||
| Writing CSS code from scratch can be boring and stressful, and sometimes it is a pain to maintain. | ||
| [TailwindCSS](https://github.com/tailwindlabs/tailwindcss) fills this gap, marking itself as a utility-first CSS framework for rapidly building custom user interfaces. It also 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 auto-reload options in order to speed up site development. | ||
| ```bash | ||
| npm run develop | ||
| ``` | ||
| ```bash | ||
| python tools/build.py --watch | ||
| ``` | ||
| ### Building for production | ||
| ```bash | ||
| npm run build | ||
| ``` | ||
| ```bash | ||
| python tools/build.py | ||
| # 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 publicly accessible 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 do we generate the page from templates? | ||
|
|
||
| The **build tool** (`tools/build.py`) uses the `config/config.json` file in order to know which pages should be built and how to build them. | ||
|
|
||
| Multiple pages are defined in `config/config.json`, and each page has its own `template` and `env`. | ||
|
|
||
| ### But in `templates/index.html`, there's an `[[ include "components/header.html" ]]`. What that does mean? And how we should use `env`? | ||
|
|
||
| The **build tool** uses [Renoir](https://github.com/emmett-framework/renoir) under the hood as a templating engine. Renoir is easy, production-ready and has 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: | ||
| ```json | ||
| ... | ||
| { | ||
| "template": "index.html", | ||
| "env": { | ||
| "name": "Kivy" | ||
| } | ||
| } | ||
| ... | ||
| ``` | ||
| And the following snippet in `index.html` | ||
| ```html | ||
| <p>Hi, [[ =name ]]</p> | ||
| ``` | ||
|
|
||
| Will produce the following output, when the template has been built: | ||
|
|
||
| ```html | ||
| <p>Hello, Kivy</p> | ||
| ``` | ||
|
|
||
| ## How about the styling (CSS)? | ||
|
|
||
| Writing CSS code from scratch can be boring and stressful, and sometimes it is a pain to maintain. | ||
|
|
||
| [TailwindCSS](https://github.com/tailwindlabs/tailwindcss) fills this gap, marking itself as a utility-first CSS framework for rapidly building custom user interfaces. It also 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 auto-reload options in order to speed up site development. | ||
|
|
||
| ```bash | ||
| npm run develop | ||
| ``` | ||
|
|
||
| ```bash | ||
| python tools/build.py --watch | ||
| ``` | ||
|
|
||
| ### Building for production | ||
|
|
||
| ```bash | ||
| npm run build | ||
| ``` | ||
|
|
||
| ```bash | ||
| python tools/build.py | ||
| ``` |