# 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
```bash
pip install tinyssg
````
## Usage
### directory structure
Configure the directory as follows.The directory name can be changed with an optional argument.
```text
|-- 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.
```python
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
```bash
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
```bash
python -m tinyssg gen
```
HTML files will be generated in the `dist` directory.
### options (excerpt)
```text
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
```python
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
```python
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
```python
from tinyssg import TinySSGPage
import markdown
class MarkdownPage(TinySSGPage):
def translate(self, basestr: str) -> str:
return markdown.markdown(basestr)
```
pages/index.py
```python
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)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "tinyssg",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ssg, static site generator, html",
"author": "Uniras",
"author_email": "tkappeng@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/da/f2/35c4fa8883109bc4ad54ab9f8a9db4f9ef61f741a02faa70234132873e7b/tinyssg-1.2.1.tar.gz",
"platform": null,
"description": "# TinySSG\r\n\r\n## Overview\r\n\r\nTinySSG is a simple static site generator with file-based routing.\r\nIt combines simplicity and flexibility by writing pages in Python code with a simple structure.\r\n\r\n## Install\r\n\r\n```bash\r\npip install tinyssg\r\n````\r\n\r\n## Usage\r\n\r\n### directory structure\r\n\r\nConfigure the directory as follows.The directory name can be changed with an optional argument.\r\n\r\n```text\r\n |-- pages Place Python files for SSG deployment.\r\n |-- libs Place Python files that are not SSG target files (e.g. libraries).\r\n |-- static Place static files that are not subject to SSG (css, images, etc.)\r\n |-- 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.\r\n |-- static The static directory is copied to this directory.\r\n```\r\n\r\n### Creating pages\r\n\r\nCreate a Python file in the `pages` directory and create a class that extends the `TinySSGPage` class.\r\n\r\n```python\r\nfrom tinyssg import TinySSGPage\r\n\r\nclass IndexPage(TinySSGPage):.\r\n def query(self) -> any:\r\n return {\r\n 'title': 'Index', 'content': 'Hello, World!\r\n 'content': 'Hello, World!'\r\n }\r\n\r\n def template(self) -> str:\r\n return self.indent(\"\"\"\r\n <!DOCTYPE html>\r\n <html>\r\n <head>\r\n <meta charset=\"utf-8\" />\r\n <title>{{ title }}</title>\r\n </head>\r\n <body>\r\n <h1>{{ title }}</h1>\r\n <p>{{ content }}</p>\r\n </body>\r\n </html>\r\n \"\"\", 0)\r\n```\r\n\r\nBuilding it will generate an HTML file with the same name as the Python file.\r\nIf 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.\r\n\r\nThe `query` method returns the data to be passed to the template, and the `template` method returns the HTML template.\r\nTinySSG uses the return values of these methods to generate HTML.\r\n\r\nThe data returned by the `query` method must be in Python dictionary format or Python dictionary list format.\r\nIn 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.\r\nIf 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.\r\n\r\nBy 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,\r\nYou can also override the `render` method for more complex processing, or use a template engine such as Jinja2.\r\n\r\nYou can also define a process to convert the rendered text to final HTML by overriding the `translate` method.\r\nIf you use the markdown library here to describe the process of conversion, you can write the template in Markdown instead of HTML.\r\n\r\nEach 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.\r\n\r\n### Start local server for development\r\n\r\n```bash\r\npython -m tinyssg dev\r\n```\r\n\r\nThe local server for development will be started.You can see the generated HTML by accessing `http://localhost:8000`.\r\n\r\nIf you change files in the `pages`, `libs`, or `static` directories, the server will automatically restart to reflect the changes.\r\n\r\n### Generating HTML\r\n\r\n```bash\r\npython -m tinyssg gen\r\n```\r\n\r\nHTML files will be generated in the `dist` directory.\r\n\r\n### options (excerpt)\r\n\r\n```text\r\nusage: python -m tinyssg [--page PAGE] [--static STATIC] [--lib LIB] [--input INPUT] [--output OUTPUT] [--port PORT] [--wait WAIT] [--nolog] [--noreloadnoreload] [--noopen] [--curdir CURDIR] [mode]\r\n\r\nMODE:\r\n\r\n Specifies startup mode (gen = generate HTML files, dev = start local server for development).\r\n\r\nOptions:\r\n --page PAGE, -p PAGE Directory for page files\r\n --static STATIC, -s STATIC Directory for static files\r\n --lib LIB, -l LIB Directory for library files\r\n --output OUTPUT, -o OUTPUT Specify output directory.\r\n --input INPUT, -i INPUT Specifies which files to include in SSG (if not specified, all files in the directory are included).\r\n --port PORT, -P PORT Specify the port number of the development server.\r\n --wait WAIT, -w WAIT Wait time to prevent multiple restarts.\r\n --nolog, -n Do not output request log to development server\r\n --noreload, -r Don't restart development server automatically.\r\n --noopen, -N Do not open browser when starting development server\r\n --curdir CURDIR, -C CURDIR Specify current directory.\r\n```\r\n\r\n## FAQ\r\n\r\n### **Q.** How can I use jinja2 as a template engine?\r\n\r\n**A.** Override the `render` method to use jinja2 to render templates.\r\n\r\nlib/jinja2_page.py\r\n\r\n```python\r\nfrom tinyssg import TinySSGPage\r\nfrom jinja2 import Template\r\n\r\nclass Jinja2Page(TinySSGPage):\r\n def render(self, src: str, data: dict) -> str:\r\n template = Template(src)\r\n return template.render(data)\r\n```\r\n\r\npages/index.py\r\n\r\n```python\r\nfrom tinyssg import TinySSGPage\r\nfrom lib.jinja2_page import Jinja2Page\r\n\r\nclass IndexPage(Jinja2Page):\r\n def query(self) -> any:\r\n return {\r\n 'title': 'Index', 'content': 'Hello, World!'\r\n }\r\n\r\n def template(self) -> str:\r\n return self.indent(\"\"\"\r\n <!DOCTYPE html>\r\n <html>\r\n <head>\r\n <meta charset=\"utf-8\" />\r\n <title>{{ title }}</title>\r\n </head>\r\n <body>\r\n <h1>{{ title }}</h1>\r\n <p>{{ content }}</p>\r\n </body>\r\n </html>\r\n \"\"\", 0)\r\n```\r\n\r\n### **Q.** How do I use Markdown to write in my templates?\r\n\r\n**A.** Override the `translate` method and use the Markdown library to convert it to HTML.\r\n\r\nlib/markdown_page.py\r\n\r\n```python\r\nfrom tinyssg import TinySSGPage\r\nimport markdown\r\n\r\nclass MarkdownPage(TinySSGPage):\r\n def translate(self, basestr: str) -> str:\r\n return markdown.markdown(basestr)\r\n```\r\n\r\npages/index.py\r\n\r\n```python\r\nfrom tinyssg import TinySSGPage\r\nfrom lib.markdown_page import MarkdownPage\r\n\r\nclass IndexPage(MarkdownPage):\r\n def query(self) -> any:\r\n return {\r\n 'title': 'Index', 'content': 'Hello, World!'\r\n }\r\n\r\n def template(self) -> str:\r\n return self.indent(\"\"\"\r\n # {{ title }}\r\n\r\n {{ content }}\r\n\r\n This is **Markdown** template.\r\n \"\"\", 0)\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A simple static site generator",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/uniras/tinyssg",
"Repository": "https://github.com/uniras/tinyssg"
},
"split_keywords": [
"ssg",
" static site generator",
" html"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d7fd95bb9fc5c27de79bfea3881ac2877f6e108e396c70f686bab6271da2ef29",
"md5": "e3edd4b2342cfb355801a9d7cd1e058a",
"sha256": "f1c6175f0a72294592eaca7947492a587914850e97e3618c1a1bb88d1e4fd463"
},
"downloads": -1,
"filename": "tinyssg-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3edd4b2342cfb355801a9d7cd1e058a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10859,
"upload_time": "2025-02-24T09:51:08",
"upload_time_iso_8601": "2025-02-24T09:51:08.853901Z",
"url": "https://files.pythonhosted.org/packages/d7/fd/95bb9fc5c27de79bfea3881ac2877f6e108e396c70f686bab6271da2ef29/tinyssg-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "daf235c4fa8883109bc4ad54ab9f8a9db4f9ef61f741a02faa70234132873e7b",
"md5": "7dac4cc1c6dc39c581dad9823ece8efa",
"sha256": "b31d4b14e68b5fe488fd7eb39c9f11c251f785254a052149e69228bbdadf416c"
},
"downloads": -1,
"filename": "tinyssg-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "7dac4cc1c6dc39c581dad9823ece8efa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13071,
"upload_time": "2025-02-24T09:51:10",
"upload_time_iso_8601": "2025-02-24T09:51:10.815419Z",
"url": "https://files.pythonhosted.org/packages/da/f2/35c4fa8883109bc4ad54ab9f8a9db4f9ef61f741a02faa70234132873e7b/tinyssg-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-24 09:51:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uniras",
"github_project": "tinyssg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tinyssg"
}
JSON
