158 lines
3.8 KiB
Markdown
158 lines
3.8 KiB
Markdown
|
---
|
||
|
|
title: Quickstart
|
||
|
|
---
|
||
|
|
|
||
|
|
# Quickstart
|
||
|
|
|
||
|
|
[TOC]
|
||
|
|
|
||
|
|
## Installation options
|
||
|
|
|
||
|
|
### Via pip from PyPI
|
||
|
|
|
||
|
|
Just run:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pip install Peji
|
||
|
|
```
|
||
|
|
|
||
|
|
### Via setup.py
|
||
|
|
|
||
|
|
You should already have the Python `setuptools` package installed.
|
||
|
|
|
||
|
|
Clone repo:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://gitea.gch.icu/ge/peji.git
|
||
|
|
cd peji/
|
||
|
|
```
|
||
|
|
|
||
|
|
Run:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pip install .
|
||
|
|
```
|
||
|
|
|
||
|
|
pip automatically runs `setup.py` and install all dependencies.
|
||
|
|
|
||
|
|
## Command line interface
|
||
|
|
|
||
|
|
Pēji provides small command line interface.
|
||
|
|
|
||
|
|
App supports only two commands:
|
||
|
|
|
||
|
|
`create SITE`
|
||
|
|
: Create new site in directory SITE. For example:
|
||
|
|
|
||
|
|
```
|
||
|
|
peji create mysite
|
||
|
|
```
|
||
|
|
|
||
|
|
In `mysite/` dir will be created standard file structure. See [Site structure](#site-structure) below.
|
||
|
|
|
||
|
|
`build`
|
||
|
|
: Render HTML pages and place it with other static content into `mysite/build/` directory.
|
||
|
|
|
||
|
|
You can choose specific directory instead of `build/` if pass `-d` (or `--dir`) option. For example, build site into `my_static_site/`:
|
||
|
|
|
||
|
|
```
|
||
|
|
peji build -d my_static_site/
|
||
|
|
```
|
||
|
|
|
||
|
|
## Site structure
|
||
|
|
|
||
|
|
After creating site you have this site structure:
|
||
|
|
|
||
|
|
```
|
||
|
|
mysite/
|
||
|
|
├── config.yaml
|
||
|
|
├── layouts
|
||
|
|
│ ├── base.j2
|
||
|
|
│ └── index.j2
|
||
|
|
├── pages
|
||
|
|
└── themes
|
||
|
|
└── default
|
||
|
|
├── css
|
||
|
|
│ └── main.css
|
||
|
|
├── images
|
||
|
|
└── js
|
||
|
|
```
|
||
|
|
|
||
|
|
There is:
|
||
|
|
|
||
|
|
config.yaml
|
||
|
|
: Site configuration file. See more [here](/configuration.html).
|
||
|
|
|
||
|
|
layouts/
|
||
|
|
: This folder contains Jinja2 templates. By default `base.j2` and `index.j2` is used.
|
||
|
|
|
||
|
|
pages/
|
||
|
|
: Place your markdown files here.
|
||
|
|
|
||
|
|
themes/
|
||
|
|
: Contains CSS, JS and images that need for page design.
|
||
|
|
|
||
|
|
build/
|
||
|
|
: Generated HTML files. Creates after running `peji build`.
|
||
|
|
|
||
|
|
## Pages
|
||
|
|
|
||
|
|
### Page metadata.
|
||
|
|
|
||
|
|
Like many other static site generators and flat-file CMS, in Pēji metadata is required for Markdown files.
|
||
|
|
|
||
|
|
Metadata must be appended to the beginning of the markdown file and is surrounded by a triple minus sign at the beginning and end. Data are presented in YAML format. Example:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
---
|
||
|
|
title: My page title
|
||
|
|
layout: index.j2
|
||
|
|
theme: my_theme
|
||
|
|
---
|
||
|
|
|
||
|
|
# Your markdown text here
|
||
|
|
```
|
||
|
|
|
||
|
|
At the moment the application only supports these three properties. Consider each:
|
||
|
|
|
||
|
|
title
|
||
|
|
: Page title. Is appended in HTML `<title></title>`.
|
||
|
|
|
||
|
|
Default: No default value. This property is required.
|
||
|
|
|
||
|
|
layout
|
||
|
|
: You can set custom template for specific page. Template file must be placed into `layouts/` directory.
|
||
|
|
|
||
|
|
Default: `index.j2`
|
||
|
|
|
||
|
|
theme
|
||
|
|
: Custom theme (CSS) for page. By default themes are placed into `themes/<theme_name>/`. In this property you only need to specify the `<theme_name>`, you don't need to specify the path.
|
||
|
|
|
||
|
|
Default: `default`
|
||
|
|
|
||
|
|
## Templates (Layouts)
|
||
|
|
|
||
|
|
### Page variables
|
||
|
|
|
||
|
|
Page variables are passed to Jinja2 templates. Below is a description of each variable. A colon separated from the name of a variable indicates its type (see [Python Data Types](https://www.w3schools.com/python/python_datatypes.asp){target="_blank"}, [[Docs]](https://docs.python.org/3/library/datatypes.html){target="_blank"}).
|
||
|
|
|
||
|
|
theme: str
|
||
|
|
: Page theme. Can be specified in page metadata. Otherwise, the value from `config.yaml` is used.
|
||
|
|
|
||
|
|
title: str
|
||
|
|
: Required property, set in the page metadata.
|
||
|
|
|
||
|
|
site_title: str
|
||
|
|
: Site title. Optional, set in `config.yaml` (named `title`). See [Configuration](/configuration.html#title-and-description).
|
||
|
|
|
||
|
|
description: str
|
||
|
|
: See. [Configuration](/configuration.html#title-and-description).
|
||
|
|
|
||
|
|
menu: dict
|
||
|
|
: Contains a dictionary where the key is the title of the link and the key value is the URL of the link. The data is filled from `config.yaml`'s `menu`.
|
||
|
|
|
||
|
|
content: str
|
||
|
|
: This is a string containing HTML-converted Markdown text. In the template, this variable must be used with `safe` to avoid escaping HTML tags. Usage example:
|
||
|
|
|
||
|
|
`{{ content | safe }}`
|