add docs
This commit is contained in:
parent
97129d058c
commit
9aed2f4727
19
docs/README.md
Normal file
19
docs/README.md
Normal file
@ -0,0 +1,19 @@
|
||||
# Pēji site
|
||||
|
||||
Pēji documentation.
|
||||
|
||||
# Build
|
||||
|
||||
Install Pēji first:
|
||||
|
||||
```
|
||||
pip install Peji
|
||||
```
|
||||
|
||||
Build:
|
||||
|
||||
```
|
||||
peji build
|
||||
```
|
||||
|
||||
Done!
|
||||
30
docs/config.yaml
Normal file
30
docs/config.yaml
Normal file
@ -0,0 +1,30 @@
|
||||
# Site title.
|
||||
title: Pēji
|
||||
# Site meta description.
|
||||
description: Stupidly simple static site generator.
|
||||
# Site default theme.
|
||||
theme: default
|
||||
# Site menu.
|
||||
menu:
|
||||
Home: /
|
||||
Quickstart: /quickstart.html
|
||||
Configuration: /configuration.html
|
||||
Downloads: /downloads.html
|
||||
Source Code: https://gitea.gch.icu/ge/peji
|
||||
Other Projects: https://gitea.gch.icu/ge
|
||||
# Markdown extensions.
|
||||
# See https://python-markdown.github.io/extensions/
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- codehilite
|
||||
- extra
|
||||
- meta
|
||||
- toc
|
||||
markdown_extension_configs:
|
||||
codehilite:
|
||||
noclasses: true
|
||||
use_pygments: true
|
||||
pygments_style: default
|
||||
toc:
|
||||
title: Table of contents
|
||||
toc_depth: 2-5
|
||||
27
docs/layouts/base.j2
Normal file
27
docs/layouts/base.j2
Normal file
@ -0,0 +1,27 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" dir="ltr">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width">
|
||||
<title>
|
||||
{% block title %}{% endblock %}
|
||||
</title>
|
||||
{% block head %}{% endblock %}
|
||||
</head>
|
||||
<body>
|
||||
<h1 style="font-size: 48px; font-weight: 300; margin-bottom: 14px;">Pēji</h1>
|
||||
<span style="font-size: 14px;"><i>Stupidly simple static site generator.</i></span>
|
||||
{% if menu %}
|
||||
<div class="menu">
|
||||
<ul>
|
||||
{% for link in menu.keys() %}
|
||||
<li><a href="{{ menu.get(link) }}">{{ link }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% block content %}
|
||||
Nothing here.
|
||||
{% endblock %}
|
||||
</body>
|
||||
</html>
|
||||
9
docs/layouts/index.j2
Normal file
9
docs/layouts/index.j2
Normal file
@ -0,0 +1,9 @@
|
||||
{% extends 'base.j2' %}
|
||||
{% block title %}{{ title }} | {{ site_title }}{% endblock %}
|
||||
{% block head %}{{ super() }}
|
||||
<link rel="stylesheet" href="/themes/{{ theme }}/css/main.css">
|
||||
<link rel="shortcut icon" href="/themes/{{ theme }}/images/favicon.ico" type="image/x-icon">
|
||||
{% endblock %}
|
||||
{% block content %}
|
||||
{{ content | safe }}
|
||||
{% endblock %}
|
||||
BIN
docs/pages/Peji-1.0.tar.gz
Normal file
BIN
docs/pages/Peji-1.0.tar.gz
Normal file
Binary file not shown.
84
docs/pages/configuration.md
Normal file
84
docs/pages/configuration.md
Normal file
@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Configuration
|
||||
---
|
||||
|
||||
Pēji provide simple configuration file in YAML format.
|
||||
|
||||
<details markdown="1">
|
||||
<summary>Config example...</summary>
|
||||
```yaml
|
||||
# Site title.
|
||||
title: Pēji
|
||||
# Site meta description.
|
||||
description: Stupidly simple static site generator.
|
||||
# Site default theme.
|
||||
theme: default
|
||||
# Site menu.
|
||||
menu:
|
||||
Home: /
|
||||
Quickstart: /quickstart.html
|
||||
Configuration: /configuration.html
|
||||
Download: /download.html
|
||||
# Markdown extensions.
|
||||
# See https://python-markdown.github.io/extensions/
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- codehilite
|
||||
- extra
|
||||
- meta
|
||||
- toc
|
||||
markdown_extension_configs:
|
||||
codehilite:
|
||||
noclasses: true
|
||||
use_pygments: true
|
||||
pygments_style: default
|
||||
toc:
|
||||
title: Table of contents
|
||||
toc_depth: 2-5
|
||||
```
|
||||
</details>
|
||||
|
||||
[TOC]
|
||||
|
||||
## Title and description
|
||||
|
||||
The **title** on each page looks like this:
|
||||
|
||||
```jinja2
|
||||
# In browser:
|
||||
page title | site title.
|
||||
# In template (default layout):
|
||||
{% block title %}{{ title }} | {{ site_title }}{% endblock %}
|
||||
```
|
||||
|
||||
Of course, the view can be changed in the layout. Pēji will pass both values to the template.
|
||||
|
||||
The *page* title is specified in the markdown file metadata (See: [Page metadata](/quickstart.html#page-metadata)). The *site* title is set in the `config.yaml`. If `title` is not specified, it will be accepted as an empty string.
|
||||
|
||||
Site **description** in unused in default layout, but you can use it if you want. Also if `description` is not specified, it will be accepted as an empty string.
|
||||
|
||||
## Themes
|
||||
|
||||
A **theme** is just a collection of static JS, CSS, and images. Any code can be there, there are no restrictions.
|
||||
|
||||
To make it easier to "switch themes", each theme is located in its own folder inside `themes/`, for example:
|
||||
|
||||
```
|
||||
themes
|
||||
├── default
|
||||
│ ├── css
|
||||
│ ├── images
|
||||
│ └── js
|
||||
└── my_theme
|
||||
├── css
|
||||
├── images
|
||||
└── js
|
||||
```
|
||||
|
||||
In the standard layout theme is connected in the `index.j2`, but it can be set in a layout that is convenient for you.
|
||||
|
||||
```jinja2
|
||||
<link rel="stylesheet" href="/themes/{{ theme }}/css/main.css">
|
||||
```
|
||||
|
||||
`config.yaml` sets the default theme, which is used if a page does not have a theme specified in the metadata.
|
||||
18
docs/pages/downloads.md
Normal file
18
docs/pages/downloads.md
Normal file
@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Downloads
|
||||
---
|
||||
|
||||
# Downloads
|
||||
|
||||
**Pēji 1.0**
|
||||
|
||||
2021.04.12
|
||||
|
||||
- Source code: [Peji-1.0.tar.gz](Peji-1.0.tar.gz)
|
||||
|
||||
---
|
||||
|
||||
Source code is also available in git repository:
|
||||
|
||||
- [gitea.gch.icu](https://gitea.gch.icu/ge/peji){target="_blank"}.
|
||||
- [mirror on GitHub](https://github.com/gechandesu/peji){target="_blank"}.
|
||||
66
docs/pages/index.md
Normal file
66
docs/pages/index.md
Normal file
@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Home
|
||||
---
|
||||
|
||||
**Pēji** (Japanese: ページ, "page") is simple way to generate small static site like this site.
|
||||
|
||||
If you need to collect several pages from the Markdown, then Pēji are great for you.
|
||||
|
||||
!!! note "**Note**"
|
||||
Pēji is not intended to generate a blog site. Its single pages only. You can link pages with hyper-links, but you have to do it manually.
|
||||
|
||||
Features:
|
||||
|
||||
- [Python-Markdown](https://python-markdown.github.io/){target="_blank"} is used.
|
||||
- Code syntax highlighting via [Pygments](https://pygments.org/){target="_blank"}.
|
||||
- [Jinja2](https://jinja.palletsprojects.com/en/2.11.x/){target="_blank"} template engine.
|
||||
- Custom style and layout for specific page.
|
||||
- Site menu bar can be edited through the config.
|
||||
- YAML config file.
|
||||
|
||||
## Installation and quickstart
|
||||
|
||||
Install Pēji globally or into virtual environment:
|
||||
|
||||
```bash
|
||||
pip install Peji
|
||||
```
|
||||
|
||||
Create your site:
|
||||
|
||||
```bash
|
||||
peji create mysite
|
||||
cd mysite/
|
||||
```
|
||||
|
||||
Create your first page and place it into `mysite/pages/`:
|
||||
|
||||
`index.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: My first page
|
||||
---
|
||||
|
||||
# My heading
|
||||
|
||||
It works!
|
||||
```
|
||||
|
||||
Build your site:
|
||||
|
||||
```
|
||||
peji build
|
||||
```
|
||||
|
||||
Site will be placed in `./mysite/build`.
|
||||
|
||||
Also you can run Python built-in HTTP Server:
|
||||
|
||||
```bash
|
||||
python3 -m http.server --directory build/
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Pēji is released under The Unlicense. See [https://unlicense.org/](https://unlicense.org/){target="_blank"} for detais.
|
||||
BIN
docs/pages/peji_jp_speech.mp3
Normal file
BIN
docs/pages/peji_jp_speech.mp3
Normal file
Binary file not shown.
157
docs/pages/quickstart.md
Normal file
157
docs/pages/quickstart.md
Normal file
@ -0,0 +1,157 @@
|
||||
---
|
||||
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 }}`
|
||||
103
docs/themes/default/css/main.css
vendored
Normal file
103
docs/themes/default/css/main.css
vendored
Normal file
@ -0,0 +1,103 @@
|
||||
body {
|
||||
margin: 32px;
|
||||
font-size: 16px;
|
||||
color: #000000;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
|
||||
hr {
|
||||
border: none;
|
||||
border-top: 0.5px solid;
|
||||
}
|
||||
|
||||
a,
|
||||
a:active,
|
||||
a:visited {
|
||||
color: #3f37c9;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:hover {
|
||||
border-bottom: 1px dashed;
|
||||
}
|
||||
|
||||
|
||||
.menu {
|
||||
margin: 18px 0 28px 0;
|
||||
}
|
||||
|
||||
.menu ul {
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.menu ul li {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
padding-right: 8px;
|
||||
display: inline-block;
|
||||
list-style: none;
|
||||
}
|
||||
|
||||
.menu ul li::before {
|
||||
content: '|';
|
||||
position: relative;
|
||||
left: -6px;
|
||||
}
|
||||
|
||||
.menu ul li:first-child::before {
|
||||
content: none;
|
||||
}
|
||||
|
||||
pre {
|
||||
padding: 12px;
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
dt {
|
||||
font-weight: bold;
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
dd {
|
||||
margin-top: 8px;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
details summary {
|
||||
cursor: pointer;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.admonition {
|
||||
padding: 0 16px;
|
||||
}
|
||||
|
||||
.info {
|
||||
color: #055160;
|
||||
background-color: #cff4fc;
|
||||
border: 1px solid #055160;
|
||||
}
|
||||
|
||||
.note {
|
||||
color: #084298;
|
||||
background-color: #cfe2ff;
|
||||
border: 1px solid #084298;
|
||||
}
|
||||
|
||||
.tip {
|
||||
color: #0f5132;
|
||||
background-color: #d1e7dd;
|
||||
border: 1px solid #0f5132;
|
||||
}
|
||||
|
||||
.warning {
|
||||
color: #664d03;
|
||||
background-color: #fff3cd;
|
||||
border: 1px solid #664d03;
|
||||
}
|
||||
|
||||
.danger {
|
||||
color: #842029;
|
||||
background-color: #f8d7da;
|
||||
border: 1px solid #842029;
|
||||
}
|
||||
BIN
docs/themes/default/images/favicon.ico
vendored
Normal file
BIN
docs/themes/default/images/favicon.ico
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Loading…
Reference in New Issue
Block a user