API for Almoststatic

Almoststatic is composed by two classes, Almoststatic is the base class that do all the job and FlaskAlmoststatic that simply bind Almoststatic to a Flask app.

class almoststatic.Almoststatic

Almoststatic uses Jinja2 template system to build web pages and web sites.

Pages are declared in yaml files and rendered with Jinja2 template files, the “content” directory contain all is needed to do the job, the “config.yaml” is used to share global parameters and to tune configuration.

load_config(config_file='content/config.yaml')

Load the yaml config file and set some configuration settings.

It is mandatory to use it at least once. It can update default configuration values and config page globals.

During development config file can change often, so can be useful to call it each time the page is reloaded.

It also configure the environment for Jinja2 and setup some utilities that can be used in templates.

Parameters:

config_file (str) – name and path of config file

build_page(pagename, **kwargs)

This is the main method used to render pages. The pagename is the url used to search yaml file into ./content/pages directory and sub folders. The page is rendered building it from “content” key of yaml file and if required contents can be embedded recursively into other contents or can be read including files. The result is the rendered page. If cache is enabled, the page is rendered only once.

In Flask this method must be called within a route, and the method write_static call it for every pages of site.

Parameters:

  • pagename (str) – the name of page (url) to build.

  • **kwargs – optional parameters used to pass dynamic contents

Returns:

the text of rendered page

Return type:

str

write_static(pages=None, destination='.', media_prefix=None, static_url=None, out_pages=[])

Write html pages on disk! If pages is None, all pages declared in content/pages folder are rendered as html and written on disk.

The suffix of url is set to “.html” and the value is stored into global vars so internal links during rendering can be changed from “page” to “page.html”, in the same way, prefix of pages can be changed form “/” to whatever is needed in the target static site.

This method change some internal parameters that are different from dynamic and static pages.

Destination indicate the folder where save files and media_prefix lets you to modify url’s for media files to point to real data location.

Parameters:

  • pages (list) – If None all pages are written as static, else only pages in the list are rendered.

  • destination (str) – insert the destination path folder where pages will be written

  • media_prefix (str) – This optional parameter let to change the pathname for media contents which can differ from development environment and destination site.

  • static_url (str) – This optional parameter let to change the url prefix for local links, so if the destination is https://www.example.com/mysite with prefix /mysite/ all links works fine

  • out_pages (list) – list of pages excluded from writing

write_json_meta(filename='site_meta.json', destination='.')

Write metadata of pages as json file to disk. So if needed javascript can read them to build client side logics.

Note

This method usually is not needed, because each time Almoststatic starts and the first page is rendered, metadata are written on: ./content/media/site_meta.json so metadata can be found there.

Parameters:

  • filename (list) – Name of json file to write

  • destination (str) – destination path folder for json file

invalidate_cache()

Delete all cached pages to force re rendering… if needed, simple!

class almoststatic.FlaskAlmoststatic(app=None)

Almoststatic can be integrated into Flask web framework. This lets to write dynamic sites with some static contents and/or for the development of static sites.

Parameters:

app (flask.app) – the flask app where Almoststtic is attached.

init_app(app)

Add some config parameters and rules to the app to bind the extension

Parameters:

app (flask.app) – the flask app where Almoststtic is attached.