69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# Tianyi CodeLab Homepage
|
|
|
|
This repository contains the source code of [Tianyi CodeLab Homepage](https://lty.name/).
|
|
|
|
## Site Builder 101
|
|
|
|
Tianyi CodeLab Homepage is built with a site builder developed by ourselves. The site builder is written in Python, and it is available in this repository.
|
|
|
|
To build the homepage, you need install the prerequisites listed below:
|
|
- Python 3.12
|
|
- [PDM](https://pdm-project.org/)
|
|
|
|
|
|
After installing the prerequisites and cloning the repository, you can build the homepage by running the following commands:
|
|
|
|
```bash
|
|
pdm install
|
|
pdm start
|
|
```
|
|
|
|
## A Deep Dive
|
|
### Directory Structure
|
|
|
|
The directory structure of this repository is as follows:
|
|
|
|
- `data/{slug}.yaml`: The render context data for the `.html` pages.
|
|
- `html/{slug}.html`: The `.html` templates. The site builder will render the `.html` pages with the data in the corresponding `.yaml` files with Jinja2.
|
|
- `public/`: The assets/public files directory. Files in this directory will be copied directly to the `dist`.
|
|
- `dist/`: The output directory of the site builder.
|
|
- `images`: The directory to place images. Note that the images will be copied to `/assets` path instead of `images`.
|
|
|
|
### Build Process
|
|
The build process is as follows:
|
|
1. Read each `.html` file in the `html/` directory.
|
|
2. Render the HTML pages.
|
|
- The site builder will render each `.html` file with the corresponding `.yaml` file in the `data/` directory.
|
|
- Outputs will be placed in the `dist/` directory with `.html` extension.
|
|
- One example is rendering `html/hi/home.html` with `data/hi/home.yaml` to `dist/hi/home.html`. If the `.yaml` file does not exist, the site builder will render the `.html` file with an **empty context** (`{}`).
|
|
- Ohter files not having `.html` extension will be **ignored**.
|
|
3. For each images in `images/`, the site builder do the following:
|
|
- For `jpg, jpeg, png` images, convert them to `webp` format. For example. `images/hi.png` will be converted to `dist/assets/hi.webp`.
|
|
- For `ico, svg, webp` images, copy them directly to the `dist/assets` directory.
|
|
- Other files will be **ignored**.
|
|
4. Copy the files in the `public/` directory to the `dist/` directory recursively.
|
|
|
|
For all the steps, hidden files (files starting with `.`) will be **ignored**.
|
|
|
|
### HTTP Server Considerations
|
|
|
|
We use prettified URLs that strips `.html` extension. To make this work on server, you need to configure the server to rewrite the URLs. Here is an example of Nginx configuration:
|
|
|
|
```nginx
|
|
location / {
|
|
try_files $uri $uri/ $uri.html =404;
|
|
}
|
|
```
|
|
|
|
We also use `home.html` instead of `index.html` for better-looking URLs. You also need to configure the server. Here is an example of Nginx configuration:
|
|
```nginx
|
|
index home.html index.html;
|
|
```
|
|
|
|
Please note that such url-prettifying behavior is optional. It is not built-in in the site builder, but in our site source code we choose to use it.
|
|
|
|
## License
|
|
The content is shared under the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license,
|
|
|
|
Some resources may have their own licenses. Trademark ristricions may apply.
|