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 <var> 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 <var>.<markname>.

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/
```

In order to make the sidebar always hidden, I had to remove the !important
from the media queries for -sidebar.  The sidebar was also made always
hidden since it intefers w/ the sidenotes from Tufte CSS.

There is a bug where w3-ul does not restrict it's li styling to the
immediate children.  Add a `>` to restrict it.

Hack to make a CSS only clickable be exposed in order to handle the nav bar:
https://stackoverflow.com/questions/6019845/show-hide-div-on-click-with-css

List of filters: `jinja2/filters.py` (`FILTERS`) and `hyde/ext/templates/jinja.py` (`self.env.filters`)

Notes on Twitter
================

A Python module `twauth.py` stores credentials.  It should contain
a memember `twit_argskw` that is a tuple of (args, kwargs).  These will be used
as arguments to the Twitter instance.  Here is a sample:

```
from twitter import OAuth

tok = 'thetoken'
tokkey = 'tokenkey'

apikey = 'apikeyfromrunningthis'
apisec = 'apisecretkey'

twit_argskw = (), dict(auth=OAuth(tok, tokkey, apikey, apisec))

__all__ = [ 'twit_argskw' ]

if __name__ == '__main__':
	from twitter import oauth_dance

	oauth_dance('pytwscr', tok, tokkey)
```

TODO
====

Using triple back-tick will eat blank lines due to wrapping them in code tags,
which will not have any characters in them.  Figure out how to fix this.