Html pages

Kask sites can have both Markdown and Html based pages. While the Markdown files provide simple notation to write long articles without clutter and offer per-section customizability; Html files are customizable on per-page basis.

Templating engine

Under the hood, Kask uses Go templating engine. Thus, developers can refer to the official text/template documentation for topics not covered by Kask documentation.

Template structure

Kask loads all shared template files stored inside the .kask folder of containing folder and its parent folders for rendering all .tmpl ending files in a content directory.

{{define "page"}}
<html>
  <head></head>
  <body>{{.Date}}</body>
</html>
{{end}}

contact.tmpl

Unlike Markdown based pages; template based pages of the same folder can have different layouts and styling. Just define the "page" template at the each page file, where customization is desired.

Page title

Kask render the "title" template for each Html based page to acquire the user given title for those, when available. To enable this behavior; define a second template named "title" as below inside the files of each desired page:

{{define "title"}}Life is life, na na nana na.{{end}}

songs.tmpl

If you desire, you might reuse the "title" template inside your "page" template:

{{define "title"}}Life is life, na na nana na.{{end}}

{{define "page"}}
<html>
<head>
<title>{{template "title"}}</title>
</head>
</html>
{{end}}

songs.tmpl

For those pages that doesn’t contain a "title" named template Kask will derive a title using the filename.

Templating content

Kask provides a series of useful, dynamic information to templates at the moment they are opened for rendering to static HTML. The struct provided to template file is called TemplateContent, which contains many fields:

type TemplateContent struct {
  Stylesheets []string
  Node, Root  *Node
  Markdown    *markdown.Page
  Time        time.Time
}

Node (sitemap item) information:
- Title of node, extracted from the source file’s name, or the H1 tag of markdown file if available.
- Href for other pages to link.
- Children, which is a list of Nodes.
Root information:
- The root Node of the website, typically hrefs to the / of website. This is usefull to start printing a sitemap. Just define a recursive template.
List of stylesheets for template to include in <head>. See Hierarchical CSS Splitting
Date in Go time.Time type. Useful to print the year to footer.

Escaping

For any text looks like a code piece; the underlying templating engine, thus Kask, will transform it in order to avoid harmful content end up running on the browser of visitors.

To place specific and trusted code on the page as is; you are presented with a series of options:

Function name	Use case
`trustedCss`	Stylesheet, CSS rule production and values
`trustedHtml`	HTML document fragments
`trustedHtmlAttr`	HTML attributes
`trustedJs`	EcmaScript5 expressions
`trustedJsStr`	Escaped JS
`trustedSrcSet`	Image srcset value
`trustedUrl`	Trusted URLs

Use proper function to bypass code escaping. Just as in the example in Markdown section:

{{define "markdown-page"}}
<html>
  <body>
    <main>{{trustedHtml .Markdown.Content}}</main>
    <aside>{{trustedHtml .Markdown.Toc}}</aside>
  </body>
</html>
{{end}}

See the markdown contents are passed through the trustedHtml function. This will allow preserving the rich format of the original document like headings, paragraphs, tables and codefences.

Those functions only enable the use of templating engine provided types CSS, HTML, HTMLAttr, JS, JSStr, Srcset and URL inside your templates. Visit individual links for details. Mind caps.

Use the trusted utilities only when you trust the document to be free of any harmful content.