Skip to content
A ClojureScript coding environment for beginners.
Branch: master
Clone or download
Latest commit 7b258e6 Mar 9, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci -A:release in circleci Mar 5, 2019
.github
blog Initial blog setup with perun Oct 16, 2017
cells WIP(deps) Mar 5, 2019
curriculum Curriculum: fix typo with incorrect description of vector May 10, 2018
editor deps Mar 8, 2019
friendly fix(build) Mar 14, 2018
shapes Shapes: refactor color-names May 10, 2018
.gitignore fix(prose): delete Mar 5, 2019
CNAME Create CNAME Nov 12, 2017
README.md remove webpack from build, update lark/tools Mar 5, 2019
_config.yml Set theme jekyll-theme-minimal Jul 19, 2017

README.md

Maria

The ClojureScript coding environment for beginners.

(Part editor, part curriculum. A collaborative work by @daveliepmann, @jackrusher, and @mhuebert.)

Why?

Our work is not to teach, but to help the absorbent mind in its work of development. –Maria Montessori

A recurring problem newcomers have with Clojure is that one must learn everything at once: the JVM, and stack traces, and a new editor, and functional programming, and and and.... What if we shielded folks new to Clojure from the complexity of tooling, stack traces, and programming language esoterica? What if we got out of their way and let them feel the power of programming for themselves? This project aims to delay or remove as many of these obstacles as possible so that people can explore.

The Maria editor is a code playground. There is no installation, zero configuration, and explaining how to make it work takes approximately one sentence. Clojure's sharp edges are rounded off, for instance, by wrapping stack traces so errors are presented humanely. A handful of helper functions do the same for types and SVG shapes. We use in-place evaluation because we find it the most effective and humane way to interact with a computer.

The curriculum we use alongside the editor uses progressive disclosure of the language, to prevent overwhelming folks. Instead of explaining all Clojure's many features as a functional, hosted lisp--which is a big topic--we introduce folks to programming and let language features follow. In this spirit, we named the project after pedagogical pioneer Maria Montessori, whose method "stresses the development of a [learner's] own initiative and natural abilities, especially through practical play" and "at their own pace".

Play

So...please go to maria.cloud and play around with it live! :)

Contributing

We welcome your effort to make the beginner's path to Clojure smoother. Here's how:

Contributing to fixing bugs

The most helpful thing you can do is simply play around! 😸 and report bugs as GitHub issues.

Contributing to better error messages

While you play around, please send us any un-wrapped Clojure error you find. We track these in the Error Handling wiki. This is so helpful for making errors easier for new people!

Please edit the wiki directly to add your experience. Or, file a GitHub issue explaining what you were doing and what error came up. Our goal with this is to protect users from jargon-filled error messages, and that requires lots of eyes pointing out all the ways a particular error could cause trouble.

Contributing to the curriculum

Like Clojure itself, the Maria curriculum is open-source, but is not primarily a community effort. We've chosen a particular approach and we write with a particular voice for a particular audience. Therefore other approaches, although valid, may not belong here. With that caveat, those of us who write the curriculum are open to contributions, which have been accepted according to these rough guidelines:

  • for typos, bugs, and obvious mistakes, we actively welcome your issues and pull requests

  • if you built something cool, please show us! :) it may end up in our Gallery of examples, if you're OK with that

  • for more substantial contributions, from suggestions for phrasing up to entirely new modules, we ask that you do the following to be on the same page as us:

    With that shared understanding attained, please get in touch with us by email so we can discuss ideas in depth.

Development

git clone https://github.com/mhuebert/maria.git;

Navigate to the /editor directory:

cd editor;

Install javascript dependencies:

npm install;

build in development mode, start a local server, and live-reload changes:

npm run watch;

When these builds have completed, open your web browser to http://localhost:8701.

running a REPL

The default nrepl port, configured in shadow-cljs.edn, is 7888.

Once connected, the following will print out a list of things you can do:

(require '[shadow.cljs.devtools.api :as shadow])
(shadow/help)

to directly enter the live environment (provided you've opened up your browser):

(shadow.cljs.devtools.api/repl :live)

make a production build:

npm run release;

License

The curriculum is licensed as Creative Commons Attribution 4.0 (CC BY 4.0).

The Shapes and Friendly libraries are distributed under the Eclipse Public License 2.0.

See LICENSE files in relevant subdirectories.

You can’t perform that action at this time.