jashkenas--coffeescript/documentation/sections/literate.md

## Literate CoffeeScript

Besides being used as an ordinary programming language, CoffeeScript may also be written in “literate” mode. If you name your file with a `.litcoffee` extension, you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code. The compiler will treat any indented blocks (Markdown’s way of indicating source code) as code, and ignore the rest as comments.

Just for kicks, a little bit of the compiler is currently implemented in this fashion: See it [as a document](https://gist.github.com/jashkenas/3fc3c1a8b1009c00d9df), [raw](https://raw.github.com/jashkenas/coffeescript/master/src/scope.litcoffee), and [properly highlighted in a text editor](http://cl.ly/LxEu).

I’m fairly excited about this direction for the language, and am looking forward to writing (and more importantly, reading) more programs in this style. More information about Literate CoffeeScript, including an [example program](https://github.com/jashkenas/journo), are [available in this blog post](http://ashkenas.com/literate-coffeescript).
-												Docs improvements: content in Markdown, organization into subtemplates, fixed tests (#4401)

* Replace tiny bitmaps with base64-encoded URIs

* Optimize SVGs; replace logo PNG with SVG

* Modernize favicon

* Embed CSS; a bit unorthodox, but we’re a single page so there’s no point in separate .css files and their separate HTTP requests

* Documentation is now markdown, converted to HTML on compilation

* Render the examples when we’re rendering index.html; they compile so quickly that there’s no need to pre-render them and save the intermediate .js files

* Split apart index.html into components that Cakefile assembles, so that we can add in logic to include different files for v1 versus v2

* Split building index.html and building test.html into two tasks; collapse the parts of `releaseHeader` into one compact function

* Move include logic into templates

* Get error messages tests to work in the browser

* Update output index.html

* Split body into nav and body

* Watch subtemplates

* Revert "Split body into nav and body"

This reverts commit ec9e559ec0c3f350bd009afd437652347789b180.

* Add marked

* Update gitignore

* Use idiomatic markdown output for code blocks (<pre><code>)

* Handle ids within the template, not in the Cakefile; remove marked’s auto-generated and conflicting ids

* Move the `codeFor` function into versioned folders, so that v1 and v2 docs can have different example code blocks/editors

* Update packages, including new highlight.js which supports our newer keywords and triple backticks (docs output is unchanged)

											
										
										
											2016-12-15 21:05:44 -08:00
+								## Literate CoffeeScript
 								Besides being used as an ordinary programming language, CoffeeScript may also be written in “literate” mode. If you name your file with a `.litcoffee` extension, you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code. The compiler will treat any indented blocks (Markdown’s way of indicating source code) as code, and ignore the rest as comments.
 								Just for kicks, a little bit of the compiler is currently implemented in this fashion: See it [as a document](https://gist.github.com/jashkenas/3fc3c1a8b1009c00d9df), [raw](https://raw.github.com/jashkenas/coffeescript/master/src/scope.litcoffee), and [properly highlighted in a text editor](http://cl.ly/LxEu).
 								I’m fairly excited about this direction for the language, and am looking forward to writing (and more importantly, reading) more programs in this style. More information about Literate CoffeeScript, including an [example program](https://github.com/jashkenas/journo), are [available in this blog post](http://ashkenas.com/literate-coffeescript).