clojure / clojure-site

clojure.org site

README

This web site is an open-source repository of content about the Clojure programming language and its greater ecosystem, hosted at https://clojure.org.

Contributing

If you wish to point out an issue in the site or propose a new page, you can do so by filing a GitHub issue at https://github.com/clojure/clojure-site/issues.

If you wish to make a contribution (typo, modification, or new content), you must become a contributor and follow the contribution process.

Building the Site

The site is built using JBake.

To install JBake 2.6.5:

1. curl -L -O https://dl.bintray.com/jbake/binary/jbake-2.6.5-bin.zip (or download this file with your browser)

2. unzip -o jbake-2.6.5-bin.zip

3. Add jbake-2.6.5-bin/bin to your system PATH

To build the site:

Retrieve the content:

1. git clone https://github.com/clojure/clojure-site.git (or your own fork)

2. cd clojure-site

Retrieve and install the current theme assets (these don’t change very often so you don’t need to do this every time):

1. curl -O https://clojure.org/clojuretheme.zip (or download this file with your browser to the clojure-site directory)

2. unzip -o clojuretheme.zip

Generate the pages:

1. jbake -b - this will create the static site in the output directory

2. Run jbake -s to serve these pages at http://localhost:8820/index

Terms of Use

Copyright © 2016-2022 Rich Hickey and contributors

All documentation contained in this repository is licensed by Rich Hickey under the Eclipse Public License v1.0 unless otherwise noted. To submit a pull request or other contribution, you must sign the Clojure Contributor Agreement.

clojure-site's Issues

Clojure Cheatsheet refers to Clojure 1.6

The Clojure Cheatsheet appears to refer to Clojure 1.6. It's missing transducers and update, from what I noticed.

Introduction to Clojure for Non-Programmers Section

Could we make a section for new-comers to programming; introducing them to programming through Clojure?

Mobile style problems

I did go through the top-level pages on my phone and found few small style problems.

Tested on Chrome device mode and Chrome Android.

Frontpage: Missing padding

Frontpage: Missing padding

Common: Missing padding and overlapping text

API and Releases: Missing padding

The additional scrollbar is only displayed on desktop browser.

Fix swag page

This page didn't survive the transition intact - need to fix it up.

Thread macros guide

Would be nice to have an overview and examples of all the threading macros

Modify guide template to indicate original author

Seems like it would be nice for that attribution to be visible.

Convert contributors list into data

The current contributor list is maintained manually in text. As the first step towards automating the contributor list, I need to convert that text list into data (in particular an external csv file with fields for name and github id).

Asciidoc supports inclusion of tables built from an external csv data file.

JVM hosted page example

https://github.com/clojure/clojure-site/blob/master/content/about/jvm_hosted.adoc uses a Swing app as the big wall of example here. I don't think that's really the best choice here (also the image is currently missing as I never fixed that up). Would like to have one or two small but recognizable examples that shows value of tapping into the JDK or Java library.

clojure.org/Transducers 404's

This is the top link on Google for "clojure transducers".

If I search in the box on clojure.org I just get the same broken result.

Content: mention the Clojure Toolbox?

www.clojure-toolbox.com is a good resource for finding Clojure libraries, especially as it makes an effort to track and prefer more active libraries over abandoned projects. May be worth mentioning.

Guide to printing

It would be nice if there was a page (or possibly more than one) about print/println vs pr/prn vs pprint and how to extend each of them.

Document read order for clj/cljs/cljc

Probably on libs page, per discussion at https://groups.google.com/d/msg/clojure-dev/d5Hb1E7zfHE/ACYLp1FxCgAJ

Reader Conditionals guide

The page on the reader has a section on Reader Conditionals and is written from the perspective of someone using the reader (as it should be). However it doesn't offer a lot of concrete advice or examples for how people can use Reader Conditionals in their code. Would you be open to a new page on Reader Conditionals? It could also briefly discuss prior art (e.g. cljx) so people new to Clojure can understand how Reader Conditionals fit and why they were created.

I've written http://danielcompton.net/2015/06/10/clojure-reader-conditionals-by-example and would be happy to adapt parts or all of it for this doc page.

Typo: "Dynamic Devemopment" link

At the bottom of http://clojure.org/about/state there is a link to "Dynamic Devemopment".

Destructuring guide

"Getting Started" area needs work

There needs to be a better Getting Started page (probably actually more than one page) that covers:

• basic facts about Clojure as a jar in the Java ecosystem
• how to start a repl from the bare jar for the purposes of just trying simple stuff
• how people typically use Clojure for a project (moving into Leiningen territory)
• how to use various tools - in some cases, better documentation exists elsewhere and this means pointing to it

Build docs for `clojure.core.server`

It looks like the API docs may not have been built for clojure.core.server? On the direct linking page, it links to the clojure.repl-api namespace which doesn't seem quite right.

Additionally, there is a repl function provided that is slightly customized for use with the socket server in clojure.core.server/repl.

clojure.org/Namespaces deadlinks

Searching for "namespace" the first google link points to clojure.org/Namespaces which gives a 404. I suppose it should redirect to

http://clojure.org/reference/namespaces

Does the capital N make a problem?

Document the collection class/interface hierarchy

How is anyone supposed to know that PersistentQueue exists?
How is anyone supposed to know what a clojure.lang.MapEntry or a clojure.lang.ISeq are? Note that parts of the documentation and some docstrings explicitely mention some of the collection interfaces but nowhere are they documented or even just listed.

Clojure news on the home page

I think it would be nice to have a small 'Clojure News & Updates' section on the front page, maybe towards the bottom. It would be a nice clean way for veteran users to stay up to date as well as a way for new users to see up front (literally) that keeping the Clojure community involved is a key priority. Some articles about releases, new tools, Clojure success stories, and so on, I think, would be a nice feature to have.

Anyone else?

Misleading namespace link and thoughts regarding namespace nomenclature.

http://clojure.org/reference/reader

'/' has special meaning, it can be used once in the middle of a symbol to separate the namespace from the name, e.g. my-namespace/foo. '/' by itself names the division function.

namespace here links to http://clojure.org/reference/namespaces which starts with "Namespaces are mappings from simple (unqualified) symbols to Vars and/or Classes."

This is not a good idea because the namespace of a symbol or keyword is not coupled to a "Clojure namespace".

• The link should be removed and a simple explanation should follow stating that a symbol can optionally have a namespace and this is mostly used to refer to Vars in "Clojure namespaces".

"Clojure namespaces" is just my idea how to solve the nomenclature clash. IMHO it (or a better alternative) should be applied consistently in the reference. It is based on the assumption that no one will stop calling Clojure namespaces "namespaces" in favor of a totally different name and the other assumption that somebody new to the language would get it wrong at least.

The name "Clojure namespace" seems "correct" since "Clojure namespaces" serve the specific purpose of organizing code in a Clojure program while namespaces of symbols or keywords are general purpose namespaces in the literal sense of the word namespace. Think of "Clojure namespace" as the word namespace with the namespace "Clojure" :)

The paragraph about keywords mentions the :: reader syntax and again suggests tight coupling to Clojure namespaces while it doesn't mention that keywords can have any namespace which only adds to the at least incomplete impression.

• The :window/rect syntax should be explained before the :: convencience

Error on Clojure eXchange event

On the http://clojure.org/community/events page the date for Clojure eXchange shows as 2016-12-02 but the first day of the conference is actually 2016-12-01.

Add redirects from old site pages to new ones

A Google search for metadata takes me to http://clojure.org/Metadata, but it's new home is at /reference/metadata. It could be good to add redirects to the new page locations for the docs that existed before the new site.

Core.async page

What do you think about adding a page discussing core.async? I don't think I've seen any official documentation on usage. There is https://github.com/clojure/core.async/blob/master/examples/walkthrough.clj but I think some more documentation could be helpful.

Add a brand/logo usage page

There seems to be a slow but steady flow of people trying to use the Clojure logo in ways that aren't allowed by Rich (unintentionally). It could be good to have a page under Community which talks about the allowed usage of the Clojure logo and the word Clojure as well.

Confusing sentence on frontpage

Tried to find the index.adoc page so I could make the change myself but that doesn't appear to be here.

The error from http://clojure.org/index:

Additionally, Clojure’s maps, sets, and vectors are as first class in Clojure 
are lists are in Lisp.

Should be

Additionally, Clojure’s maps, sets, and vectors are as first class in Clojure 
as lists are in Lisp.

Please add Clojure eXchange 2016 Event to events page

Clojure eXchange 2016

If you're looking for the best place to learn about Clojure, Functional Programming and network with like-minded people, then the Clojure eXchange 2016 is the conference you simply can't miss! Meet with the world's leading experts, learn how to use Clojure in your team and discuss war stories with your peers.

Location: CodeNode, London, UK
Link: https://skillsmatter.com/conferences/7430-clojure-exchange-2016
Dates: 1st-2nd December 2016

Please add ClojureBridge London to Clojure.org events page

ClojureBridge London 2016

We're offing this workshop to help make the Clojure community more accessible to a diverse range of participants. As such, this event is only welcoming participants who identify as female or nonbinary. Males may register as a guest of one of these participants.

This workshop is intended for those with none/some programming experience.

Link: http://www.clojurebridge.org/events/2016-02-19-london
Location: London, UK
Dates: 19th-20th February 2016

Code Editor Setup Guides

Might be considered a consumer of #32

But an attempt to include links to, or guides for, setting up code editors with various configurations which lend themselves well to Clojure development would be very handy.

Should have clojure code on the front page

Most devs will expect to see some example code when visiting the home-page of a programming language. Currently clojure.org has none.

Examples of language home-pages with tasteful code blocks:

• Ruby (https://www.ruby-lang.org/en/)
• Python (https://www.python.org/)
• Elixir (http://elixir-lang.org/)
• Racket (http://racket-lang.org/)

Incorporate a "try/clojure" REPL

See the home page for Rust: https://www.rust-lang.org/

Try/clojure is a lovely project, but the casual browser of clojure.org won't know how to interpret "TryClojure provides a browser-based Clojure REPL" and may not click through.

To elaborate, if I follow the path "clojure.org" -> "clojure.org/getting_started" as a new user, the term REPL is as yet undefined for me. So I won't know that "a browser-based Clojure REPL" means "play with some Clojure code in your browser."

On the other hand, if there's an edit box with code in it and a "run me" button, then it's pretty clear what I'm looking at.

atom.io + parinfer

Hi,

A guide for atom.io + parinfer would be awesome.
I've used it to teach some classes where I work.
Unfortunately, I'm not using it daily (I use vim), but I've noticed that It simplifies what scares many newcomers to lisp.
For the repl piece we ended up using the lein repl with require reload.

Regards,

Geraldo

Robots file missing

It looks like www.clojure.org/robots.txt is 404'ing, and there used to be a sitemap for clojure.org which is also missing.

Link to clojure style guide

Link: https://github.com/bbatsov/clojure-style-guide

I personally felt relieved when I found out it existed - I could check my code against the guide and learn from that - "minor" things (vs. functionality), but might help gain confidence nonetheless for beginners.

Comparators guide

Would be cool to see this guide by @jafingerhut turned into a guide: https://github.com/jafingerhut/thalia/blob/master/doc/other-topics/comparators.md

Note: this should only be done with Andy's ok! That's his copyright.

cannot access from china

I'm not sure where clojure.org is hosted, but it's currently block from china

 <<>> DiG 9.8.3-P1 <<>> clojure.org
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 59644
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;clojure.org.           IN  A

;; ANSWER SECTION:
clojure.org.        3599    IN  A   75.126.104.177

;; Query time: 133 msec
;; SERVER: 8.8.8.8#53(8.8.8.8)
;; WHEN: Mon Nov 16 11:58:01 2015
;; MSG SIZE  rcvd: 45

can I suggest if it's a static site, would it be better if just host on gh-pages?

A few more books!

This list: https://www.reddit.com/r/Clojure/comments/3q9jaw/clojure_releases_vs_clojure_book_publication_dates/
seems to mention a few more books than the site http://clojure.org/community/books

Please extend the "official list" with the missing one, and also having the publication dates would be really helpful.

Thank you.

Proposal: would you please add one line introduce to each library?

http://clojure.org/api/api
In this page , we list these libraries:
Clojure Contrib Libraries

algo.generic
algo.graph
algo.monads
core.async
core.cache
core.contracts
core.incubator
core.logic
core.match
core.memoize
core.rrb-vector
core.typed
core.unify
data.avl
data.codec
data.csv
data.finger-tree
data.fressian
data.generators
data.json
data.priority-map
data.xml
data.zip
java.classpath
java.data
java.jdbc
java.jmx
math.combinatorics
math.numeric-tower
test.generative
tools.analyzer
tools.analyzer.js
tools.analyzer.jvm
tools.cli
tools.emitter.jvm
tools.logging
tools.macro
tools.namespace
tools.nrepl
tools.reader
tools.trace

But would you please add one line introduce to each library ? to help new user to easy know what the library does quickly.

Socket REPL guide

It could be good to expand docs on the socket REPL to:

• Explain motivations for creating the socket REPL
• Explain how it can be used or extended
• Explain how it is different from the current Clojure REPL, and nREPL
• Discuss the streaming nature of the REPL

There is some good information in the design doc that could be collated for this.

Section for Video Courses

Please improve the links to learning materials from "other" sources too :)

Another one important besides the existing books could be a "Video Courses" section. Just a few of existing video courses (in no particular order):

• Building Microservices with Clojure Training Video - http://www.infiniteskills.com/training/building-microservices-with-clojure.html
• Learning ClojureScript Training Video - http://www.infiniteskills.com/training/learning-clojurescript.html
• Learning Clojure Training Video - http://www.infiniteskills.com/training/learning-clojure.html
• Up and Running with Clojure - http://www.lynda.com/Clojure-tutorials/Up-Running-Clojure/413127-2.html
• Clojure Inside Out - http://shop.oreilly.com/product/0636920030409.do
• Communicating Sequential Processes with core.async - http://shop.oreilly.com/product/0636920041474.do
• Functional Thinking - http://shop.oreilly.com/product/0636920030393.do
• Building Web Applications with Clojure - https://www.packtpub.com/web-development/building-web-applications-clojure-video
• Clojure Concurrency - https://www.pluralsight.com/courses/clojure-concurrency-tutorial
• Clojure Fundamentals - Part 1 - https://www.pluralsight.com/courses/clojure-fundamentals-part-one

Thank you.

clojure cheatsheet -- link colors make text hard to read (not enough color contrast)

When looking at the clojure cheatsheet, I find the link colors hard to read, because the contrast is too low for me, on my monitor.

Doing some element inspection in my browser, the link color is defined as #4C82DF on a background of rgba(235, 241, 245, 0.66), which converts to #EBF1F5. If you throw those values into a color contrast checker, it says that it isn't enough contrast for the W3C's Accessibility Guidelines.

I think something like #304890 is much easier to read, while still being a somewhat similar blue. It also passes the W3C guidelines, even the AAA ones.

Add RSS or Atom feed for the News section

It would be nice to add feed for this section, so the news could be propagated to Planet Clojure.

Expose visitors to very basic examples of Clojure code

It seems that someone landing on the home page should be shown an example of Clojure code, even if it is only something as simple as '(println "Hello World"!)'

Giving the user a lot of text to read before seeing any code will increase the chance they will navigate away from the site.

If having front page code is not desirable then maybe just a side-bar (or side-bar link) to a page dedicated to basic code examples would help.

Clojure.org does have a Getting Started page but it is almost too minimal as well as too advanced. There is an example of launching the REPL (better off shown later?) and a math example. The Language sections on the getting started page talk about Comparators and Reader Conditionals, fairly advanced topics for the total newbie.

I'd suggest something like the following, possibly as examples in the REPL (e.g. with output):

Hello world example

(println "Hello world")
=> Hello World

Calling a built-in math function

(+ 1 1)
=> 2

Defining an array

(def my-array [1 2 3])

Printing my-array

etc...

Defining a function

(defn add-two [x](+ x 2))

Calling your new add-two function

etc. etc.

If this is something the maintainers would like to see I can put something together with actual page of markdown, etc. to provide a starting point.

Wrong date on 1.8 release date

https://clojure.org/news/news says "25 November 2015"

https://clojure.org/news/2016/01/19/clojure18 correctly says "19 January 2016"

Direct linking guide

It could be good to have a guide on using direct linking which:

• Shows an example of how to set it up in a Leiningen and Boot application
• Shows in a REPL/code session how var indirection is removed with direct linking on
• Explains where you are likely to need ^:dynamic and ^:redef
• Shows an example of code that gets speed improvements from direct linking with benchmarks
• Which code direct linking applies to (just your code, or all your dependencies too?)
• How to distribute direct linked libraries
• Any tradeoffs or other reasons why you wouldn't want to use direct linking

Multi-Lingual

I suggest the new clojure.org be made in more than one language.

If there's interest, I can contribute a mulit-lingual CMS http://yajogo.com/en/

Thanks

Simon

news & guide pages should have a list rather than take you to first item

Go to http://clojure.org/news/2016/01/14/clojure-org-live and hit the 'news' link. You end up at clojure.org/news/news which displays the 2016-01-14 article.

Same applies to the guides link -- linking to guides/ but displaying a guide instead of a listing of guides.

The events listing page DOES provide a listing of events.

expected is in all three cases a LISTING of ENTITY instead of you selecting a random entity for me.

Use different colours for strings and comments

Strings and comments both have a very similar, if not the same colour. It could be good if they had different colours so they are more easily distinguished.

Api page would look better if it has a few columns

http://clojure.org/api/api page has only one column currently. There is a lot of white space to the right on a desktop screen. A few columns would look better.

Hashing and equality guide

Would be cool to see @jafingerhut 's page on equality and hashing turned into a guide. With his approval since he owns the copyright!!

https://github.com/jafingerhut/thalia/blob/master/doc/other-topics/equality.md