A simple static site generator
Project description
TinySSG
Overview
TinySSG is a simple static site generator with file-based routing. It combines simplicity and flexibility by writing pages in Python code with a simple structure.
Install
pip install tinyssg
Usage
directory structure
Configure the directory as follows.The directory name can be changed with an optional argument.
|-- pages Place Python files for SSG deployment.
|-- libs Place Python files that are not SSG target files (e.g. libraries).
|-- static Place static files that are not subject to SSG (css, images, etc.)
|-- dist This is the directory where SSG results will be output.The contents of this directory can be published as a web site by placing it on a web server.
|-- static The static directory is copied to this directory.
Creating pages
Create a Python file in the pages directory and create a class that extends the TinySSGPage class.
from tinyssg import TinySSGPage
class IndexPage(TinySSGPage):.
def query(self) -> any:
return {
'title': 'Index', 'content': 'Hello, World!
'content': 'Hello, World!'
}
def template(self) -> str:
return self.indent("""
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>{{ title }}</title>
</head>
<body>
<h1>{{ title }}</h1>
<p>{{ content }}</p>
</body>
</html>
""", 0)
Building it will generate an HTML file with the same name as the Python file.
If multiple TinySSGPage inherited classes are defined in the Python file, the Python file name becomes the folder name and the class name in it becomes the HTML file name.
The query method returns the data to be passed to the template, and the template method returns the HTML template.
TinySSG uses the return values of these methods to generate HTML.
The data returned by the query method must be in Python dictionary format or Python dictionary list format.
In the case of dictionary format, an HTML file is generated with the python filename or class name, and in the case of list format, a directory is created equal to the python filename or class name, and by default, an HTML file is generated with a filename of .html, a number from 1.
If a string representing a key name is returned with the list as a tuple on return, an HTML file is generated with the value corresponding to the key as the file name.
By default, TinySSG simply replaces the parts of the template enclosed in {{ key name }} with the value corresponding to the key in the dictionary that is the return value of the query method,
You can also override the render method for more complex processing, or use a template engine such as Jinja2.
You can also define a process to convert the rendered text to final HTML by overriding the translate method.
If you use the markdown library here to describe the process of conversion, you can write the template in Markdown instead of HTML.
Each page must be defined individually, but since this is a simple Python class, if you want to apply it to multiple pages, you can create a class that defines the common parts and inherit it to easily apply it without copying any code.
Start local server for development
python -m tinyssg dev
The local server for development will be started.You can see the generated HTML by accessing http://localhost:8000.
If you change files in the pages, libs, or static directories, the server will automatically restart to reflect the changes.
Generating HTML
python -m tinyssg gen
HTML files will be generated in the dist directory.
options (excerpt)
usage: python -m tinyssg [--page PAGE] [--static STATIC] [--lib LIB] [--input INPUT] [--output OUTPUT] [--port PORT] [--wait WAIT] [--nolog] [--noreloadnoreload] [--noopen] [--curdir CURDIR] [mode]
MODE:
Specifies startup mode (gen = generate HTML files, dev = start local server for development).
Options:
--page PAGE, -p PAGE Directory for page files
--static STATIC, -s STATIC Directory for static files
--lib LIB, -l LIB Directory for library files
--output OUTPUT, -o OUTPUT Specify output directory.
--input INPUT, -i INPUT Specifies which files to include in SSG (if not specified, all files in the directory are included).
--port PORT, -P PORT Specify the port number of the development server.
--wait WAIT, -w WAIT Wait time to prevent multiple restarts.
--nolog, -n Do not output request log to development server
--noreload, -r Don't restart development server automatically.
--noopen, -N Do not open browser when starting development server
--curdir CURDIR, -C CURDIR Specify current directory.
FAQ
Q. How can I use jinja2 as a template engine?
A. Override the render method to use jinja2 to render templates.
lib/jinja2_page.py
from tinyssg import TinySSGPage
from jinja2 import Template
class Jinja2Page(TinySSGPage):
def render(self, src: str, data: dict) -> str:
template = Template(src)
return template.render(data)
pages/index.py
from tinyssg import TinySSGPage
from lib.jinja2_page import Jinja2Page
class IndexPage(Jinja2Page):
def query(self) -> any:
return {
'title': 'Index', 'content': 'Hello, World!'
}
def template(self) -> str:
return self.indent("""
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>{{ title }}</title>
</head>
<body>
<h1>{{ title }}</h1>
<p>{{ content }}</p>
</body>
</html>
""", 0)
Q. How do I use Markdown to write in my templates?
A. Override the translate method and use the Markdown library to convert it to HTML.
lib/markdown_page.py
from tinyssg import TinySSGPage
import markdown
class MarkdownPage(TinySSGPage):
def translate(self, basestr: str) -> str:
return markdown.markdown(basestr)
pages/index.py
from tinyssg import TinySSGPage
from lib.markdown_page import MarkdownPage
class IndexPage(MarkdownPage):
def query(self) -> any:
return {
'title': 'Index', 'content': 'Hello, World!'
}
def template(self) -> str:
return self.indent("""
# {{ title }}
{{ content }}
This is **Markdown** template.
""", 0)
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tinyssg-1.3.0.tar.gz.
File metadata
- Download URL: tinyssg-1.3.0.tar.gz
- Upload date:
- Size: 13.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6bd37668e9a9b9685d58d64b99fc361ab445dbd0376831cad55357fb9355d4c6
|
|
| MD5 |
131566cf21871065a78d2e46630b93f0
|
|
| BLAKE2b-256 |
12d34d4a6ad99d7564759bb716d6b50613a322d99bef7604256176a7cb5b56ad
|
File details
Details for the file tinyssg-1.3.0-py3-none-any.whl.
File metadata
- Download URL: tinyssg-1.3.0-py3-none-any.whl
- Upload date:
- Size: 11.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7e4f62d30ede74d5e09e9c92bd57f66283b72d668f5533b9ad93db0a3bc9ef03
|
|
| MD5 |
853daf96ae040d37a595084e3a0a88e0
|
|
| BLAKE2b-256 |
78285e664a5428156898bbd273e02a3a6c80672abe3111a7ad02e2317b45774b
|
