Skip to content

Latest commit

 

History

History
45 lines (35 loc) · 3.57 KB

README.md

File metadata and controls

45 lines (35 loc) · 3.57 KB

Yet Another Static Site System (yasss)

The idea of this software is to support client-side websites via a minimal wrapper-structure around a Python-based templating engine (Jinja).

There is support for multiple sites via common templates as well as extensibility for developing new templates. A goal is to require minimal knowledge beyond standard web technologies (HTML, CSS, JS) and some small amount of Jinja, as well as to support a spectrum of coding style in the space of [(Python/JS) scripted, hand-coded (HTML)].

Some Terms

  • Template. A packaging of Jinja template/macro files, static resources (e.g., CSS, JS), and Python code/data to support a particular type of site.
    • Resource. A file to copy when instantiating a template (e.g., locally hosted js/css files).
    • Data. Arbitrary Python variables used to populate pages (via the Jinja templating engine).
    • Global. a variable, typically a function, supplied to the Jinja engine that becomes available to all Jinja files (template & site).
  • Site. A customized instantiation of a template, including pages (that typically will extend a template's Jinja file), site-specific resources (e.g., images, downloads), Python code, and site-specific data.
    • Build. Integrate site & template code in order to output a set of pages & resources rendered via Jinja.

Starting a Site

Let's assume a good template already exists...

  1. Create a folder that will contain your site-specific pages and resources (think of this as the state of your site)...
    • Create at least one page in this folder based upon Jinja files available for your desired template.
      • The extends path should take the form: TEMPLATE_NAME/FILE.JINJA
    • Structure resources within this folder.
  2. Create a Python file that calls the appropriate template function to build your site; each template will require various inputs, but typically...
    • site_dir: the path to the folder you created in step #1.
    • destination: the path to the folder in which to build your site (note: this folder will be deleted prior to each build).
    • pages: the list of pages (i.e., file names relative to the site folder) to render using Jinja.
    • resources: the list of files (relative to the site folder) to be copied to the destination.
      • Can also take the form of a tuple (dir, predicate), where the first is a path (relative to the site folder) to a directory, and the second is a function that indicates whether or not to copy each recursively contained file via its relative path and file name.
    • data: site-specific data to make available to site pages.
    • globals: site-specific globals to make available to site pages.

Typical Workflow

Once you have a site structure, your typical process is to...

  1. Make edits to your Python file and/or the contents of your site folder.
    • Note: the util import has some common functions for producing markup in Python (that is typically then passed as data for inclusion in pages).
  2. Run your Python file to re-build your site given the changes.
  3. Open rendered pages in the destination using your web browser.

Making a Template

  1. Create a template folder to house resources and Jinja files.
  2. (Optional, but useful.) Create a Python file with template-specific utility methods, including any customization of the site build process.
    • The gen import provides a general build function that template-specific builds can call.

Jinja has great documentation for template designers.