lask-task-runner.github.io

The documentation site for Lask, published at https://lask-task-runner.github.io/. Built with VitePress.

Where the content lives

Most pages are generated from the lask repository at build time by scripts/sync.mjs, and are not committed here:

Page	Source in lask
Language guide topics, and the overview's topic table	example/02-language/ (the README and each topic's files)
Examples	example/01-projects/*/README.md
Reference → Language specification, Compatibility policy	doc/spec.md, doc/compatibility.md

The module reference (Modules) is generated from lask-module-tools, at the tag versions.json names in tools. scripts/module-help.sh asks lask itself for the help of every function in it, as JSON (lask run --format json <fn> --help), and scripts/modules.mjs turns that and the module's README into pages: the README as the overview, and one page per category of its catalog. A function's entry is its doc comment and signature, so it is edited in that repository.

The lask repository keeps only what the implementation needs, so documentation for users is written here. To change a generated page, edit its source in the lask repository; every generated page's "Edit this page" link goes there. Written here by hand: the home page (docs/index.md), the Guide pages, including the migration guides (docs/guide/), the quick reference (docs/reference/quick-reference.md), the language guide's overview (docs/language/index.md), the navigation (docs/.vitepress/config.mts) and the lask syntax highlighting (docs/.vitepress/lask.tmLanguage.json).

Develop

You need Lask and Docker, and the lask and lask-module-tools repositories checked out next to this one. Node and VitePress run in a container (main.lask):

lask sync                              # one-time: pulls the Node image
lask run dev                           # http://localhost:5173, reloads as you edit
lask run dev --lask-src ~/src/lask     # another checkout (or set LASK_SRC; TOOLS_SRC for the module)
lask run preview                       # every version, as deployed, http://localhost:4173
lask run --help                        # every task

dev builds one version at the root, from the lask checkout as it is, whatever branch it is on. build and preview build every version in versions.json into site-dist/, each from its own refs (see Versions), so the checkout needs the lask tags and its development branch fetched.

The pages from the lask checkout are generated when dev starts; after changing it, restart dev or run lask run pages beside it. node_modules lives in a Docker volume (lask-docs-node-modules), so lask run install after package.json changes, and docker volume rm lask-docs-node-modules to start over.

Deploy

.github/workflows/deploy.yml builds and deploys to GitHub Pages on every push to main, on a lask-docs-updated repository dispatch from the lask repository, and once a day.

Versions

Each version of Lask has its own copy of the site, at /<version>/. versions.json lists them, newest first:

{ "version": "0.8.0", "site": "HEAD", "lask": "dev" }

• site: the ref of this repository the hand-written pages come from. HEAD is the checkout being deployed, so the newest version follows main.
• lask: the lask branch the generated pages come from until lask has the tag v<version>. Once the tag exists, the build uses it.

The tag is also what makes a version released. Until lask is tagged, the version switcher beside the title shows "(unreleased)"; the first build after the tag, which the daily schedule guarantees, removes it. The switcher also marks the latest release.

/ redirects to the newest released version, or to the newest version while none is released. A path without a version, such as a link from before versions existed, redirects to the same page in that version. A page a version does not have redirects to that version's home.

When a version is released and the next one starts

Once lask vX.Y.Z is published, with an authenticated gh:

lask run release X.Y.Z X.Y+1.0

It asks you to type release X.Y.Z (see lask.json), then, on main:

1. names the release in the pages: the lask version output in Getting started, and the version and sha256 in the workflow on Running in CI, taking the sha256 from what GitHub records for the linux-amd64 archive;

2. tags that state docs-X.Y.Z, frozen for the released version;

3. in versions.json, points X.Y.Z at that tag and adds the next version on top, with lask dev and the same tools:

   {
     "versions": [
       { "version": "0.9.0", "site": "HEAD", "lask": "dev" },
       { "version": "0.8.0", "site": "docs-0.8.0", "lask": "dev" }
     ]
   }
   

4. pushes main and the tag.

From then on, main describes the next version, and a fix to the released version's pages goes on a branch from its tag.