lit icon indicating copy to clipboard operation
lit copied to clipboard

dynamic selection of code blocks

Open vijithassar opened this issue 6 years ago • 0 comments

lit-node is intended for use only with JavaScript and thus requires you to add a language specifier after the fence backticks. This allows you to include code written in other non-JavaScript languages in your Markdown file (notably, Bash commands for installation) without compiling that content down to the JavaScript output.

That idea doesn't quite work for lit, which is intended to be language agnostic, but it does point toward new functionality that might be worth implementing.

lit could allow you to specify from the command line interface the code block identifier to compile. So for example, to make lit behave like lit-node as described above, you might tell it only to extract code blocks that are identified as js:

$ ./lit.sh --identifier "js"

Simple enough.

To this, I'll also suggest a few extensions:

stdio

This identifier functionality should only be available when using lit over stdio. That's because the default multi-file "compile everything" behavior bases several aspects of its behavior (which files to process, what to name output files) on the file extensions of the input files. If with this feature the same Markdown input file could include both js and sh code, then it's not always clear from the filename handling alone whether the output file should be called .sh or .js. This also doesn't provide a way to parse the file extension in cases where you use the complete language name as an identifier (which is preferable practice since it is clearer, and more literate!).

```javascript
// code goes here
```

This could be solved by including a registry of languages which map to file extensions (and comment characters); docco does this, but I'd prefer to avoid a registry of "officially supported" languages because this tool is flexible enough that it doesn't actually need that.

Extended Identifiers

In most cases where I have tested, syntax highlighting for GitHub Flavored Markdown only cares about the characters that immediately follow the backticks.

This code block is identified as JavaScript, obviously:
```js
// code goes here
```

If there are additional characters after the language identifier, they'll be ignored and syntax highlighting will still be triggered accurately. For example:

Still identified as JavaScript:
```js a
// code goes here
```

Also still identified as JavaScript:
```js a
// code goes here
```

This means that we can allow lit to extract longer (more literate?) identifiers that extend the usual simple language identifiers:

Some JavaScript for the Node.js server:
```js server
// code goes here
```

Some JavaScript for the client:
```js client
// code goes here
```

There's no limit to how deep you can go with this:

Old version of the program:
```js client stable
// code goes here
```

Experimental new version:
```js client prototype
// code goes here
```

This allows the same literate Markdown file to be compiled in different ways, routed to different output files. For example, to build the same Markdown file into executable files for client, server, and unit tests (remember, I propose requiring stdio for this new identifier flag, hence the pipe syntax):

$ cat app.md | ./lit.sh --identifier "js client" > client.js
$ cat app.md | ./lit.sh --identifier "js server" > server.js
$ cat app.md | ./lit.sh --identifier "js test" > tests.js

For maximum ridiculous flexibility, I'd suggest that --identifier might as well be plural --identifiers and contain a comma-separated string of multiple code block identifiers, all of which would be included in the output.

vijithassar avatar Nov 27 '17 00:11 vijithassar