Introducing Python-SSG: Simplifying Dynamic Static Page Rendering with Python

In recent years, Static Site Generation (SSG) has gained prominence in web development. While client-side rendering (CSR) is widely used with frameworks like React and Vue.js, there are many scenarios where SSG offers significant advantages, such as improved SEO, faster initial load times, and better accessibility for users with slow devices or connections.

With this in mind, python-ssg was developed to bring the simplicity and efficiency of SSG to the Python ecosystem. In this post, I will introduce what SSG is, the problems python-ssg addresses, and the motivations behind creating this project.

What is SSG?

Static Site Generation (SSG) is a technique where web pages are generated on the server, and the "ready" HTML is sent to the browser. This contrasts with Client-Side Rendering (CSR), where most processing and rendering occur in the browser after the page is loaded.

Some of the main advantages of SSG include:

• Better initial performance: Since the page is delivered already rendered, the initial load time can be considerably shorter.
• Improved SEO: Search engines can more easily index pages that are rendered on the server, which is crucial for sites that rely on organic traffic.
• Accessibility: Users with slower devices or unstable connections can have a better experience with SSG, as the heavy processing is done on the server.

What does python-ssg solve?

python-ssg was born out of the need to create a simple yet powerful solution for SSG in the Python ecosystem. In many projects, traditional frameworks like Django and Flask offer some form of rendering, but there are situations where these solutions are complex or excessive for what is desired.

Here are some of the main problems that python-ssg seeks to address:

1. Simplicity in integration: The idea is for python-ssg to be easy to integrate with any Python project, without depending on a specific framework.

2. Flexibility: It allows the use of custom templates and rendering mechanisms, enabling adaptation to each project's needs.

3. Better performance for dynamic sites: If your site has a lot of content that changes frequently, SSG can reduce the load on the client, and python-ssg makes this implementation easier without sacrificing performance.

4. Reduced load time: With SSG, the page can be delivered almost instantaneously to the browser, even before all JavaScript or dynamic content is loaded.

Motivations for creating python-ssg

The creation of python-ssg came from observing some gaps in the market. Many Python developers were stuck with solutions that were too robust for simple needs or purely client-side approaches that sacrificed performance and SEO. Some of the main motivations include:

• Need for a lightweight solution: In many projects, heavy frameworks like Django and Flask bring unnecessary overhead, and python-ssg offers a minimalist alternative.

• Ease of use: Many existing SSG solutions on the market are complex to integrate, requiring a considerable learning curve. python-ssg was designed to be accessible to developers with varying levels of experience.

• Catering to different scenarios: python-ssg is flexible enough to be used in both small projects and large web applications, adapting to different requirements.

How to use?

The library is simple to use. After installing with pip install python-ssg, just configure a config.json file, create HTML template files in the html/ folder, and call the start_rendering function. The JSON file allows you to define pages, associated APIs, and the rendering frequency. Here is a basic example:

config.json

{
  "pages": {
      "index": {
          "api": {
              "url": "http://127.0.0.1:5000/api/index",
              "method": "GET"
          },
          "render_interval": 5
      }
  }
}

main.py

from python_ssg import start_rendering

if __name__ == "__main__":
    start_rendering("config.json")

Feel free to create HTML templates and organize your assets in this structure:

your_project/
├── config.json
│
├── html/
│   ├── assets/
│   │   └── (Your folders and files)
│   │
│   ├── index.html
│   └── (Your HTML files)
│
├── dist/
│   └── (Rendered HTML files, generated automatically)
│
└── main.py

The html/ folder will contain the page templates that will be dynamically filled with data returned from the APIs. The generated files will be saved in the dist/ folder. Thus, when the start_rendering function is called, it will continuously update the content according to the defined rendering interval, ensuring that the information is always current with the latest data from the API.

Want to contribute?

Python-SSG is an open-source project, and I'm sharing it with the community so that we can improve and expand its functionalities together. The documentation is straightforward, and the code is easy to understand. Feel free to explore the repository, open issues, suggest improvements, or even contribute new features.

One of the planned improvements for the future is integration with AWS S3, so that the generated pages can be automatically uploaded to an S3 bucket, making it easier to update sites in the cloud.

If you want to take a look at the project, the code is available on GitHub:
https://github.com/kayon-ariel/python-ssg

Also, check it out on PyPI:
https://pypi.org/project/python-ssg/

Any feedback, ideas, or contributions are very welcome!