Blocks

At the heart of Knuth's literate program attempt was the notion of a block. It consisted of a unique heading, a body of explanatory text, and then a code block where substitutions, etc., could occur.

For this version of literate-programming, this style works and is recommended. The header is a markdown header (level is ignored by the compiler), the comments are just ordinary text, and the code block is a block indented by 4 spaces. Tabs are reserved for paragraphs in a markdown list. Example: sample.md

But more complicated structures are allowed and can be useful.

By using a link syntax at the beginning of a line, we can create a new code block within a given header block. This has a variety of uses:

1. Different types of related code in different languages/files. Think of a html/css/js widget with all the code kept together in a single heading block. Example: logs.md
2. A main code body with a few snippets here and there. This could be a small bit of functionality in code taken out to maintain the view of the flow of the work. Or if writing a body of text in lp fashion, it could be a callout or footnote kind of thing. There is no need to make a big heading, but it is nice to separate out the distracting code. Example: fizzbuzz.md
3. Var declarations in JavaScript are often put at the top of a function. But if we have different bits of code feeding into the function, the var declarations make more sense with those bits of code. So one can have a vars code block and separately a code block. Example: primes.md
4. We can also do templating using asterisk notation. The setup is that it uses separate codeblocks for plugging into the template. Example: templating.md

The choice of style is up to you and can be mixed and matched freely.