diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d95b330 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# Pēji site + +Pēji documentation. + +# Build + +Install Pēji first: + +``` +pip install Peji +``` + +Build: + +``` +peji build +``` + +Done! diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 0000000..33d68b8 --- /dev/null +++ b/docs/config.yaml @@ -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 diff --git a/docs/layouts/base.j2 b/docs/layouts/base.j2 new file mode 100644 index 0000000..213f5f2 --- /dev/null +++ b/docs/layouts/base.j2 @@ -0,0 +1,27 @@ + + + + + + + {% block title %}{% endblock %} + + {% block head %}{% endblock %} + + +

Pēji

+Stupidly simple static site generator. +{% if menu %} + +{% endif %} +{% block content %} +Nothing here. +{% endblock %} + + \ No newline at end of file diff --git a/docs/layouts/index.j2 b/docs/layouts/index.j2 new file mode 100644 index 0000000..7bfd360 --- /dev/null +++ b/docs/layouts/index.j2 @@ -0,0 +1,9 @@ +{% extends 'base.j2' %} +{% block title %}{{ title }} | {{ site_title }}{% endblock %} +{% block head %}{{ super() }} + + +{% endblock %} +{% block content %} + {{ content | safe }} +{% endblock %} diff --git a/docs/pages/Peji-1.0.tar.gz b/docs/pages/Peji-1.0.tar.gz new file mode 100644 index 0000000..5ac8772 Binary files /dev/null and b/docs/pages/Peji-1.0.tar.gz differ diff --git a/docs/pages/configuration.md b/docs/pages/configuration.md new file mode 100644 index 0000000..4628414 --- /dev/null +++ b/docs/pages/configuration.md @@ -0,0 +1,84 @@ +--- +title: Configuration +--- + +Pēji provide simple configuration file in YAML format. + +
+Config example... +```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 +``` +
+ +[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 + +``` + +`config.yaml` sets the default theme, which is used if a page does not have a theme specified in the metadata. \ No newline at end of file diff --git a/docs/pages/downloads.md b/docs/pages/downloads.md new file mode 100644 index 0000000..739b106 --- /dev/null +++ b/docs/pages/downloads.md @@ -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"}. diff --git a/docs/pages/index.md b/docs/pages/index.md new file mode 100644 index 0000000..81ce003 --- /dev/null +++ b/docs/pages/index.md @@ -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. \ No newline at end of file diff --git a/docs/pages/peji_jp_speech.mp3 b/docs/pages/peji_jp_speech.mp3 new file mode 100644 index 0000000..85e16ad Binary files /dev/null and b/docs/pages/peji_jp_speech.mp3 differ diff --git a/docs/pages/quickstart.md b/docs/pages/quickstart.md new file mode 100644 index 0000000..24b6922 --- /dev/null +++ b/docs/pages/quickstart.md @@ -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 ``. + + 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//`. In this property you only need to specify the ``, 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 }}` diff --git a/docs/themes/default/css/main.css b/docs/themes/default/css/main.css new file mode 100644 index 0000000..55c2df6 --- /dev/null +++ b/docs/themes/default/css/main.css @@ -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; +} \ No newline at end of file diff --git a/docs/themes/default/images/favicon.ico b/docs/themes/default/images/favicon.ico new file mode 100644 index 0000000..da6bb83 Binary files /dev/null and b/docs/themes/default/images/favicon.ico differ