🎮 Runnable READMEs w/ xc

adriens - Sep 12 '23 - - Dev Community

❔ About

Sometimes, to describe what your project can do ( how to build/use it) you put script in your README... then the end user (including you) has to deal with a set of commands, put them in the right order,etc...

The aim of this post is to show how to ease all this stuff, right into the README, with xc:

GitHub logo joerdav / xc

Markdown defined task runner.

xc - Simple, Convenient, Markdown-based task runner.

xc is a task runner similar to Make or npm run, that aims to be more discoverable and approachable.

The problem xc is intended to solve is scripts maintained separately from their documentation Often a Makefile or a package.json will contain some useful scripts for developing on a project then the README.md will surface and describe these scripts In such a case, since the documentation is separate, it may not be updated when scripts are changed or added. xc aims to solve this by defining the scripts inline with the documentation.

xc is designed to maximise convenience, and minimise complexity Each xc task is defined in simple, human-readable Markdown. This means that even people without the xc tool installed can use the README.md (or whatever Markdown file contains the tasks) as a source of useful…

🪝 Teaser

In the demo, you'll se how easy it is to implement and use tasks during a live coding session.

🎯 Goal

The goal can be summarized as a single issue:

🧰 Stack

  • xc : to package README as runnable tasks
  • tea.xyz : to easily install duckdb package
  • GH Codespaces : so we can code the feature right into the cloud in our browser... for the cloud
  • duckdb : serverless & lighwight database

🍿 Demo

Enough talk, let's dive into the demo:

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .