Hello, World!
This is a ‘Hello, World’ example of literate program with a Bootstrap skin.
This template should get you started with writing literate programs. The idea is, that, once you have used this template (via cookiecutter), you write your code inside a set of Markdown files in the lit directory. This Markdown is converted to runnable code on the fly by Entangled, while Pandoc generates the HTML documentation. If you use Github, these pages can be hosted from Github Pages.
In the intended workflow you edit the Markdown for content, and the code for function. Changes in the source code are automatically fed back to the Markdown by Entangled. You can extend the Makefile for extra functionality and tweak the files in the style directory for presentation. The generated pages in docs are constantly being kept up-to-date by the running Makefile.
Prerequisites
For some of these dependencies, being NodeJS and Pandoc, most Linux distributions ship a version that is usually a bit outdated and it is generally recommended to install them manually.
| Dependency | Where to get it | Why |
|---|---|---|
| GNU Make | (system) | Used to coordinate deployment. |
| Python ≥ 3.7 | (system) | Powers entangled-filters, and cookiecutter. |
tmux |
(system) | make watch will start several commands in one window. |
inotifywait |
(system) | Waits for changes, then runs Pandoc whenever needed. |
node |
NodeJS | Needed for browser-sync. |
| Pandoc | Pandoc home | Converts documents. |
dhall-to-json |
Dhall releases | Configuration language. |
cookiecutter |
pip install cookiecutter |
Create new project to this template. |
entangled-filters |
pip install entangled-filters |
Pandoc filters needed. |
browser-sync |
npm install -g browser-sync |
Serves the generated page, and automatically reloads your browser. |
entangled |
Entangled | Does what Entangled does. |
Usage
Create a new project by running cookiecutter
Watch for changes in source directories and view them in the browser
Tweaking
Makefile
The building of this page is managed by GNU Make. If you need to build your code or generate graphics this is the place to configure that.
Style
The default Bootstrap style may not always be what you want. There is an aditional CSS file in style/mods.css.
HTML Template
The template HTML is in style/template.html. If you prefer a different layout for the navigation, or wish to tweak the main layout in other ways, this is the place to do so.
Upgrading
To upgrade to the latest version of Entangled Bootstrap Cookiecutter, assuming your current working directory is the project folder
cookiecutter --replay --output-dir .. --overwrite-if-exists \
https://github.com/entangled/bootstrap.gitThis will overwrite existing files, so beware! If you want to recover your files:
and
are your friends. Alternatively, you may upgrade from a new/separate branch, using meld or vimdiff to merge the changes manually. Ideas are welcome on how to smoothen this process.
Examples
- Chaotic Pendulum: uses PureScript to run a model of a chaotic pendulum in the browser.
License
Copyright 2020 Johan Hidding, Netherlands eScience Center
This template is licensed under the Apache License, Version 2.0; you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.