Compare commits

...

3 Commits

Author SHA1 Message Date
gd
9aed2f4727 add docs 2021-12-23 21:16:51 +03:00
gd
97129d058c update requirements 2021-12-23 21:15:19 +03:00
gd
4f0d5bbc0b fix typo 2021-12-23 21:14:17 +03:00
14 changed files with 521 additions and 8 deletions

19
docs/README.md Normal file
View 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
View 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
View 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
View 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

Binary file not shown.

View 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
View 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
View 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.

Binary file not shown.

157
docs/pages/quickstart.md Normal file
View 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
View 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

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 KiB

View File

@ -266,7 +266,7 @@ def parse_page_metadata(text: str) -> dict:
else:
return None
def validate_matadata(config: dict, metadata: dict) -> dict:
def validate_metadata(config: dict, metadata: dict) -> dict:
meta = {}
if metadata:
try:
@ -361,7 +361,7 @@ def build_site(build_dir: str):
markdown_files = get_markdown_file_list(pages)
for file in markdown_files:
text = read_file(file)
meta = validate_matadata(
meta = validate_metadata(
config,
parse_page_metadata(text)
)
@ -410,4 +410,4 @@ def build(dir):
click.echo('Built in: %s' % dir)
if __name__ == '__main__':
cli()
cli()

View File

@ -1,5 +1,5 @@
click>=7.1.2
markdown>=3.3.4
Jinja2>=2.11.3
Pygments>=2.8.1
PyYAML>=5.4.1
click
markdown
Jinja2
Pygments
PyYAML