CCSM Builder

This is a static web generator for the Creative Coding Strategies for Musicians online textbook. It was created because existing generators lacked certain functionality that I was looking for. This generator has unique content generation directives similar to reStructuredText such as admonitions, as well as static image generation using D3 at compile-time.

I am currently in the process of separating the textbook content from the generator to have distinct versioning from each, as well as adding additional features. You can see the intended features here. Eventually this generator could conceivably be used by others in creating other websites.

Installation

This project uses Node to handle package dependencies. Assuming you have npm installed simply clone down this repository and run npm install. You will also need gulp to render the site content.

git clone https://github.com/gmoe/ccsm-builder
cd ccsm-builder
npm install
gulp && gulp serve

Generation Procedure

This project uses Gulp to handle build tasks, which turns Markdown source into static HTML and an Electron-based offline app. The structure of the textbook is encoded inside of JSON files that describe chapter hierarchy and page order. The rendered Markdown is then threaded through Nunjucks templates paired with the JSON data. In the future, additional Nunjucks templates will be added for ePub generation.

• gulp: Render the book into static HTML
• gulp serve: Host static content on port 8000. Content dynamically renders on source changes

Directives

Admonitions

Similar to reStructuredText admonitions, these are inline text blocks that are visually distinct from the rest of the content. This can be used to create things "Warning" and "Spotlight" messages.

{% admonition "warning", "This Is A Warning!" %}
For real though, this is a warning.
{% endadmonition %}

Code Tabs

The CCSM textbook is intended to be platform-agnostic, so each code example is demonstrated in multiple languages. This directive will generate a tabbed display where users can select their preferred language can compare the implementation against other languages. Eventually, this directive will support the pairing of static/rendered Max patches with a patch download.

{% codetabs "sc", "faust", "max" %}
play{ SinOsc.ar(440).dup\*0.1 }
{% lang %}
random = +(12345) ~ \*(1103515245); // overflowing mpy & offset
RANDMAX = 2147483647.0;
noise = random / RANDMAX;
{% lang %}
Max code here.
{% endcodetabs %}

Concept Demonstrations

This directive inserts an inline <div> element and pairs it with a <script> tag that populates the prior element. The scripts automatically have D3 pulled in as a dependency. This can be used to visually demonstrate theorems and concepts mentioned in the book, as seen below:

{% conceptdemo "phasing.js" %}
{% endconceptdemo %}

Statically Rendered SVGs

Similar to the concept demonstration directive, this will execute a fenced Javascript code block that uses D3 to render a static SVG that is embedded in the generated HTML. This enables authors to use the same workflow as the prior directive while not slowing down page loads by generating SVGs each time.

{% rendersvg "This is a caption. It's also a sphere.", "mySvg" %}
var svg = d3.select(window.document).select('svg');
svg.attr('height', 100).attr('width', 100);
svg.append('circle')
  .style('stroke', 'gray')
  .style('fill', 'rgb(241, 159, 77)')
  .attr('r', 40)
  .attr('cx', 50)
  .attr('cy', 50);
return d3.select(window.document).select('body').html();
{% endrendersvg %}