This repository contains the base-chameleon theme for the Nikola static site generator and the nti.nikola_chameleon template engine. This document will describe the structure of this theme for those that need to extend it.
- Talk about conventions: naming, macro and viewlet use, etc.
Macros should be named in three parts: the name of the template that uses them (if they are used by only one template), the selector-like path to the part of the page where they are used, and lastly their function. So a macro used in the base template directly inside the <html> element to produce the <heod> element would be called base_html_head, while one used in the content <div> inside the <body> tag (which is nested inside the <html> element) to produce content header would be called base_html_body_content_header. (Portions of the selector may be left out if the name would be too unwieldy, if it's still unambiguous.)
If a macro is globally defined and meant to be used from many templates, it may omit the template name portion.
These may be used in different page types.
- html_body_content_breadcrumbbar
From crumbs.macro.pt. Produces a
<nav>containing an<ul>with a<li>for each item in thecrumbsvariable. Used by gallery.tmpl.pt and listing.tmpl.pt.- html_body_content_archive_navigation
From archive_navigation_helper.pt. Produces a
<nav>containing a<ul>with a<li>for the previous, next, and parent archive. Used in list.tmpl.pt and list_post.tmpl.pt for IArchivePageKind pages.- html_body_content_pager
Produces a
<ul class="pager">with entries for previous and next pages. There is a generic version used in indexes and a version specialized for use in post pages.
Note
These do not yet follow the naming conventions. This may be changed.
There are three macros defined for comments:
- comment_link
Produce a link to the comments for a single post. This is used in index.tmpl.pt, where it is re-bound for every post:
post/@@macros/comment_link.This will set the global variable 'need_comment_script' to the context if they have ever been invoked and produced output while rendering a template. (Since we can only have one comment system at a time, this is idempotent.) You can then traverse that to get the script:
<div tal:define="global need_comment_script nothing" tal:repeat="post posts"> <metal:block metal:use-macro="post/@@macros/comment_link" /> </div> <metal:block metal:use-macro="comment_link_post/@@macros/comment_link_script" tal:condition="need_comment_script">- comment_link_script
Used in the body of pages that will be displaying comments. This produces the correct scripts.
- comment_form
Produces the HTML for viewing and adding comments.
These macros are specialized for particular comment systems as needed. (Currently only disqus is supported.)
There are two macros defined for dealing with math rendering:
- math_html_extra_head_scripts
Insert any necessary scripts for rendering into the head. This is typically included in the
extra_headviewlet.- math_html_body_content_scripts
Insert any extra scripts needed for rendering. This is usually placed at the end of the content section, next to the
comment_link_script
There are two variants of these macros, one defined for when the context actually needs MathJax or KaTeX, and one for when it doesn't, to avoid bloating pages when not needed.
These are useful for when the context is an IPostList.
- post_html_body-Content_postlist
Produce a list of posts showing date and title. This is used in the generic post list template (for tags.tmpl and author.tmpl) and in list_post.tmpl.pt.
We register a new viewlet manager type called IPostListArticle and an instance of this manager named post_list_article. This is used by the generic_post_list.pt template to implement the tags.tmpl and author.tmpl pages.
Templates are described in more detail in templates.rst.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent