Kitten

Reference sections

Kitten’s Markdown support comes from markdown-it.

Kitten supports a very rich set of Markdown features including:

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):

  1. If the page includes the new constructor: | section in the YAML front-matter, it is automatically treated as stateful.

  2. If the page is specifically marked using the stateful: true flag 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:

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.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.