Skip to content

Latest commit

 

History

History

specification

README.md

Handlebars Specification

This project fulfills two purposes:

  • Create the website of the Handlebars Specification, using http://astro.build
  • Export a list of test-cases that can be used to test a (javascript-based) Handlebars implementation against specification.

The exported test-cases are used in the other modules of this repository.

Using the AST types

import type { Program } from "@handlebars-ng/specification/ast";

will import the main type of the abstract-syntax-tree. Other node-types can be imported as well.

Using the tests

The parser-specification test and the runner-specification test are examples of using test test-cases.

import { handlebarsSpec } from "@handlebars-ng/specification/tests";

will return an array of test-cases in the defined in test.d.ts

Module structure

  • src/ - contains source-files for the website
  • src/pages/spec - contains the texts and test-cases of the specification.
  • astro-plugins/ - contains custom plugins for astro.
  • ast.d.ts - entrypoint for projects using the AST sources
  • tests.d.ts - entrypoint for projects using the test-cases
  • tests.js - JavaScript entrypoint, generated from *.hb-spec.json files in src/pages/spec

Specification syntax

The specification is written in .mdx format. Each section of the specification contains one more test-cases.

A test-case is a JSON file ending with .hb-spec.json. The file must match the testcase-schema

The section links to the test-cases via simple markdown links (i.e. [](./example.hb-spec.json)).

The plugin in astro-plugins/inject-testcase.mjs identifies such links and renders a human-readable form of the test-case into that website.

Styling

We use tailwind for styling.

Work in progress

The whole specification is very much work in progress. Apart from specs and tests, the following things are still missing:

  • A lot of markdown-styling is still missing. The SpecLayout.astro is used by specification pages and missing styles should be added there as we proceed with the spec.
  • We should generate a JSON file that contains the same data as the export of the specification module. It can then be used by implementations in other languages.