Reference sections
Reference āŗ Markdown
Kittenās Markdown support comes from markdown-it.
Kitten supports a very rich set of Markdown features including:
typographical niceties (like converting typewriter quotes āā into curly quotes āā, etc.)
adding classes, identifiers and attributes to your markdown
e.g.,
# Classy heading {.myClass #identifier attribute=value attribute2="spaced value"}A heading that contains a value gets the valueās index in its
idattribute: with no value before it,# Hello ${name}has theidhello-0. To build theidfrom the value, write it:## My ${name} {#my-${kitten.slugify(name)}}The
kitten.slugify()method takes only a string. Anidwritten this way is never numbered; give each heading a different one.e.g.,
This is my [classy span]{.myClass} and I love it!e.g.,
Inline images  are rendered normally, using just an `<img>` tag. ')e.g.,
Inline footnotes rock.^[Inline footnote are easy to write and update.]
When writing Markdown, please indent the contents of your code fences to follow the natural indentation rhythm of your page.
Specifically, do not pull them flush left in an effort to remove trailing whitespace. Kitten does this for you, intelligently, when creating your preformatted code areas in HTML.
If you do pull the code fence contents outside of the natural indentation rhythm of the page, you will get a render error.
You can use Markdown in your Kitten apps in a variety of ways:
You can create whole pages using Markdown by placing your Markdown in page.md files. These pages are transpiled into JavaScript before being rendered into HTML just like regular JavaScript pages (page.js) files.
Markdownās backslash escapes apply, and \${, \< and \} render ${, < and }, inside code too.
Your Markdown pages can have front matter in YAML format.
Kittenās YAML parser is based on the Node yaml module and you can use it directly in your own Kitten apps by referencing it from the kitten.yaml property.
Kittenās YAML front matter supports some special properties. Specifically:
You can include arbitrary JavaScript in a script block.
For example, hereās the Kitten Count example as a Markdown page with a script block:
---
script: |
let count = 1
---
# Kitten count
${'š±ļø'.repeat(count++)}
As this example shows, you can use JavaScript string interpolation inside of Markdown pages just as you would in a regular JavaScript file.
Specifies the layout template to use for the Markdown page.
The value for the layout property is a string that contains the relative path to the layout template (.layout.js file) you want to import and use.
Any custom properties in front matter are passed to the layout template as properties.
For example, if your layout template is called main.layout.js and it is located in the layouts/ folder of your project and you want to include it in a page called index.page.md at the root of your project, your front matter might look like this:
---
layout: './layouts/main.layout.js'
title: 'Feed me!'
author: 'Oskar Kalbag'
---
Woof.
And your layout template might look like this:
export default function mainLayout ({ SLOT, title, author } = {}) {
return kitten.html`
<header>
<h1>Oskarās blog</h1>
<p>I am a dog.</p>
</header>
<main>
<h2>${title} by ${author}</h2>
${SLOT}
</main>
<footer>
<p>PS. Have you fed me?</p>
</footer>
`
}
The title and author fields you see in the example above are custom properties the author wants passed to the layout template.
Each heading of a Markdown page has a link to itself. To turn heading links off for a page, set the headingLinks property to false.
Markdown pages can also be stateful.
There are two rules that determine whether your Markdown page is a stateful page (so you can add and use stateful Kitten components on it):
If the page includes the new
constructor: |section in the YAML front-matter, it is automatically treated as stateful.If the page is specifically marked using the
stateful: trueflag in the YAML front-matter.
If a stateful Markdown page has a layout, the layout must also be stateful (a kitten.Page or kitten.Component subclass). Otherwise, Kitten throws an error when it renders the page.
A quick example:
---
title: An interactive markdown page
layout: ./index.layout.js
script: |
import Reaction from './Reaction.fragment.js'
constructor: |
this.reaction = this.addChild(new Reaction())
---
# Hello!
What do you think of this page?
<${this.reaction} />
Any properties other than the special ones listed above are passed to your pageās layout template (if it has one) as props.
In a stateless Markdown page, Kitten also passes two built-in properties to the layout template:
request: reference to the KittenRequest object. (A Node.js http.IncomingMessage object as as extended by Polka and then again by Kitten. The important Kitten addition is thesessionproperty that refers to the current session.)response: reference to the KittenResponse object. (A Node.js http.ServerResponse object as extended by Kitten. Kitten mixes in a number of useful response helpers.)
This is because there is no way for you to pass them to your layout yourself in Markdown.
In a stateful Markdown page, Kitten passes your custom properties to your layout componentās constructor (as an object) and to its html() method. Your layout can reach the request and response objects via this._page.request and this._page.response.
You can place pieces of Markdown into Markdown fragment files (fragment.md).
Markdownās backslash escapes apply, and \${, \<, and \} render ${, <, and }, inside code too.
Unlike Markdown pages, Markdown fragments do not support front matter. A fragment can interpolate its props (${props.name}) and its slots, both default and named. The <div> that wraps the fragment has the props spread on it (<div ...${props}>). Pass a class or id prop to set its class or id attribute.
Finally, you can embed Markdown directly in your Kitten HTML tagged template string by surrounding your Markdown content between <markdown>ā¦</markdown> tags.
e.g.,
export default () => kitten.html`
<h1>This is HTML</h1>
<markdown>
- _This_
- is
- __Markdown!__
</markdown>
<footer>
<p>This is more HTML</p>
</footer>
`
Unlike HTML, Markdown is whitespace-sensitive so make sure you indent your code properly or it will get parsed incorrectly.
You can see some of the Markdown features mentioned here demonstrated in the examples/components and examples/markdown folders of the Kitten examples, as well as in the source for the Kitten web site itself.
In a Markdown page, each heading is followed by a link to it, which Kitten displays as a link icon in the margin before the heading. The icon appears when the pointer is over the heading (or when the link has keyboard focus), and following it puts the address of that section of the page in the browserās location bar, ready to share. On a touch screen, tap a heading to display its icon.
For example, the heading of this section (### Heading links) is rendered as:
<div class="headingWithLink">
<h3 id="heading-links" tabindex="-1">Heading links</h3>
<a class="headingLink" href="#heading-links" aria-labelledby="heading-links"></a>
</div>
The link is labelled by its heading (with the aria-labelledby attribute), so screen readers read the heading as it is displayed, in the language of your page. This also means that a heading that contains a value has a link like any other. Remember that such a heading has the valueās index in its id attribute unless you write the id yourself (e.g., ## My ${name} {#my-${kitten.slugify(name)}}). (A heading with an empty id, e.g., one that is only an image, has no link.)
To turn heading links off for a page, set the headingLinks property to false in its front matter:
---
headingLinks: false
---
Markdown fragments and the <markdown> blocks in your kitten.html donāt have heading links, as theyāre usually parts of a page. To turn them on for a block (and for the blocks inside it), add the heading-links attribute to its tag (and to turn them off for a block in a page that has them, write heading-links=false):
export default () => kitten.html`
<markdown heading-links>
## Hover over me
</markdown>
`
Kitten adds the styles for heading links to the head of your page. The element around a heading and its link has the headingWithLink class, the link has the headingLink class, and the icon is the linkās ::before pseudo-element, so you can restyle all three in your own styles. Remember to make your selectors more specific than Kittenās own (a.headingLink and a.headingLink::before), e.g., main a.headingLink.
Remember that a heading with a link is inside that element. If your styles select a heading by its parent or select what follows a heading (e.g., main > h2 or h2 + p), select the element instead (main > .headingWithLink > h2 or .headingWithLink + p).
Note that the icon is displayed in the margin, so your page must have about 1.5rem of room beside its text for it. Without that room, the icon is outside the window and the link can only be reached with the keyboard. (With Water, which the css attribute of the page tag includes, there is less room than that in windows narrower than 848px.)
You can see heading links at work in the heading links example.
Syntax highlighting in Markdown is provided via Highlight.js.
To turn on syntax highlighting for your page, include a <page> tag in your file that includes the syntax-highlighter attribute:
<page syntax-highlighter>
The default themes for light and dark mode are the Measured Light and Measured Dark accessible syntax highlighting colour scheme implementations for Highlight.js.
You can override this setting by setting the syntax-highlighter-theme-light and syntax-highlighter-theme-dark attributes of your <page> tag to the absolute or relative path to the respective theme CSS file.
View the full list of default Highlight.js themes.
See the <page> tag reference for more details.
Certain versions of the 1Password password manager browser extension appear to rewrite the Highlight.js class names in Kitten pages, thereby preventing the syntax highlighting from working. If you encounter this, please let the 1Password folks know so they can fix their code.