blog/NOTES.md

Various Notes on templating

The markdown filter is located in hyde.ext.templates.jinja, and is to be configured by addeding a markdown property to the site.yaml file, such as:

markdown:
    extensions:
        - toc
        - footnotes
        - fenced_code
        - tables
    extension_configs:
        toc:
            permalink: true

Some extensions are listed here: https://python-markdown.github.io/extensions/ but not all of them are (headerid is not, but toc implements a similar feature).

Some useful extensions: https://python-markdown.github.io/extensions/attr_list/ https://python-markdown.github.io/extensions/fenced_code_blocks/ https://python-markdown.github.io/extensions/toc/ - implement permanent links

To access the site context data, define them in the site.yaml as context->data, and it will be accessible via site.context (without the data for some reason).

Also, uses Tufte CSS, which is documented here: https://edwardtufte.github.io/tufte-css/

Another person’s site built using this: https://github.com/pattern/verdant-refuge

h1 should not be used in blog posts, as it is used by the title of the blog and in the template, h2 and h3 are fine.

the blog post entry is in macros.j2 in the render macro

A useful way to do testing: find content/ site.yaml -type f | entr sh -c ‘hyde -v gen && grep -A 20 ^BEGIN deploy/index.html’

Jinaja2 template language documentation: https://jinja2docs.readthedocs.io/en/stable/templates.html

Documentation for what variables are available in the template that hyde provides: https://hyde.readthedocs.io/en/latest/templates.html#context-variables

Resource is a template that has metadata associated with it, see hyde.site.Resource for more inforation. A Node (sibling) is a directory.

You can import a template via a {% refer to <file> as <var> %} and it appears to import a template but NOT the metadata. The appears to have a resource member which mirrors the resource structure of a normal template.

Once the “template” has been imported, any data that is surrounded by a mark tag can be accessed via ..

Dependancy tracking isn’t great. Modifying the meta.yaml file will not take effect until the files are touched/update. Make sure you do a touch * after updating the meta.yaml file.

Plugins to look at: ImageSizerPlugin -- adds image sizes to html (could be expanded to include hires versions, and and/or generate normal res versions) ImageThumbnailsPlugin -- creates thumbnails JPEGOptimPlugin -- optimize jpegs OptiPNGPlugin -- optimize PNGs TaggerPlugin -- tagger plugin

FlattenerPlugin -- this might be useful, but also useful to add in deploy paths PaginatorPlugin -- makes pages TextlinksPlugin -- converts text into links, that is /fname -> link and !!/media to a media_url UrlCleanerPlugin -- removes index.html and more GitDatesPlugin -- automatically get post dates from git

Figure out how to limit column width to a max size.

The order of the plugins DO mater!! I switched MetaPlugin to be after AutoExtendPlugin, and the yaml header appeared in the blog post.

fenced_code.py is an updated version that splits the code block into multiple code lines. This allows some css magic to add line numbers before them and not get copy/pasted. Installed via:

cp fenced_code.py p/lib/python3.8/site-packages/markdown/extensions/