The Community Docs site is powered by Github Pages. After pull requests are merged, the contents are updated automatically. Handy!
Please follow the steps below to start contributing to ClojureBridge:
Steps:
gh-pages
branch of ClojureBridge/community-docs repository.1
2
3
4
5
6
7
---
layout: docs
title: How to Contribute
permalink: /docs/contribute/
level:
author: yokolet
---
When you update existing documents, see the template documents under docs/clojure
or docs/clojure-script
directory. Those templates are written in Markdown format. If you prefer HTML, change the file extension from md to html. In the front-matter, set the author:
attribute to your GitHub alias.
When you will create a new document, create a file under docs/clojure
or docs/clojure-script
directory. However, you may create a new subdirectory if appropriate. Currently, contents lists are created manually. Go to the _data
directory and add a title and permalink. If you created a new subdirectory, add a new file under _data
. Also, edit _includes/content_list.html
layout: docs
. The docs
layout is for all documents. Don’t change this.title: something
The document title.permalink: somelink
This document’s relative URLlevel: easy
The easiness of the lab work. One of easy, intermediate, difficult.author: github-id
Write your github id (don’t write @, which causes a rendering error)1
2
3
4
5
6
7
---
layout: docs
title: How to Contribute
permalink: /docs/contribute/
level:
author: yokolet
---
Additional Info
What to write
These documents provide lab exercises or labwork for ClojureBridge attendees. They will have coaches who can help, so write more examples rather than explaining it for attendees. Then, write advice for coaches on what they can teach about the examples.
Add the difficulty level of the lab work: easy, intermediate, difficult. This will help attendees and coaches choose a good exercise considering their programming background. It might be fun to add “most difficult” labs for the coaches.
Code example
Most documents uses Jekyll’s syntax highlighter. Please look at the document, Writing posts, for details. Alternatively, you can embed gist by gist tag. See “Gist” section of Templates.
Some documents uses Klipse. This klipse plugin renders the code nicely. More importantly, the klipse acually runs the code on a browser. So, when the klipse notation is used, the result will be rendered dynamically. See docs/clojure/anonymous-function.md
and docs/clojure/truthiness.md
on an editor (not on the browser) for syntax.
When the klipse plugin doesn’t render a result as intended, try html markup. The example is around line 100 in anonymous-function.md
, <pre><code class=”language-klipse” data-eval-context=”expr”> … </code></pre>.
Running the Community Docs site locally
gh-pages
branch in your community-docs
directorygem install bundler
bundle install
Start the server
jekyll serve --incremental --watch
. This will start the server running on port 4444. --incremental
Enable incremental build making it very fast. --watch
option reflects the changes immediately.http://localhost:4444/community-docs/
. Document examples
/docs/getting-started/helloworld.md
(Hello World of Getting Started)/index.html
(“Home” page)Send us a Pull Request
Documents
Suggestions
Corrections
Design Love
File an issue and mention the github alias of an author of the document, so that the author(s) know a discussion has started about their document. Also, don’t forget to close the issue when the discussion ends. Thanks!