Skip to content

Latest commit

 

History

History
78 lines (50 loc) · 2.37 KB

constraints.md

File metadata and controls

78 lines (50 loc) · 2.37 KB
Raw

Constraints and invariants

There is no need to rerender URLs to a page, unless the target file has changed

  • A page's location does not change unless the file defining the page changes
  • A reference to a page does not change unless the target file changes

The rendered directory structure tracks the source directory structure

  • Paths in the source directory structure correspond to paths in the rendered directory structure
  • The rendered directory structure can rename nodes (index.md -> index.html)
  • The rendered directory structure can add paths (foo.md -> 'foo/index.html', or tag pages under a taxonomy root)
  • The rendered directory structure can remove paths (for example, pruning empty directories)
  • The rendered directory structure cannot move pages or directories up the directory structure (/foo/bar.md cannot become /bar.md, nor /baz/bar.md)
  • When adding contents from multiple roots, the second root inherits the metadata and existing structure from the first one
  • When adding contents from multiple roots, the second root cannot replace files from the first root
  • Asset directories however can be merged
  • The site can appear under a path instead of at the root. That affects only generated URLs, not links between pages. Source contents are completely unaware of the root path of the site when exposed on the web

Pages cannot determine the type of other pages

  • The type of a page is a function only of its format, metadata, and the metadata of the directory that contains it.

Jinja2 templates can only depend on page query expression of pages

  • TODO: log queries during jinja2 rendering
  • TODO:remember what queries a template does, and use it to trigger rerenderings based on what changed

Site generation steps

1: Features

Features are loaded from staticsite sources.

2: Theme

Themes are loaded.

After this step, all features have been loaded and initialized.

3: Dirs

Site content directories are scanned.

After this step, all source material has been mapped out.

4: Contents

Pages are created from site sources.

After this step, only autogenerated pages can be created.

5: Organize

Features can build indices as needed from the source pages loaded.

6; Generate

Create autogenerated pages.

After this step, no more pages can be added.

7: Crossreference

Final processing of page crossreferences.