How to Contribute

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:

• Fork the repository
  • All documents are in the gh-pages branch of ClojureBridge/community-docs repository.
    
    
• File the issue
  • If it is a new document, let other people know you have started working on the document. Go to CommunityDocs issues, and create a new issue. Write what document you are working on. Don’t forget to close the issue when you finish writing up.
    
    
• Edit existing or create new contents
  • Since we are using Github pages, our contents are provided by Jekyll. Currently, Github pages support HTML and Markdown formats (and textile, probably). Each document should have Front-matter on the top. This is very important. Don’t forget to add that. For example, this document has the front-matter below.

1 ---
2   layout: docs
3   title: How to Contribute
4   permalink: /docs/contribute/
5   level: 
6   author: yokolet
7   ---

• 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 URL
  • level: 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     layout: docs
3     title: How to Contribute
4     permalink: /docs/contribute/
5     level: 
6     author: yokolet
7     ---

• 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.

  • Syntax highlighter

    For HTML, and Markdown, the site is setup to use Pygments for syntax highlighter. Please look at the jekyll document, Writing posts, for details. Alternatively, you can embed gist by gist tag. See “Gist” section of Templates.

  • Running the Community Docs site locally

    1. Checkout the gh-pages branch in your community-docs directory
    2. Run gem install bundler
    3. Run bundle install
       
       

  • Start the server

    • Run jekyll serve --watch. This will start the server running on port 4444. --watch option reflects the changes immediately.
    • Open your browser and go to http://localhost:4444/community-docs/.
      
      

  • Document examples

    • Markdown: /docs/getting-started/helloworld.md (Hello World of Getting Started)
    • HTML: /index.html (“Home” page)
      
      

  • Send us a Pull Request

    • Nothing new to most of you guys. :) (but just in case - Sending The Pull Request)

What Contributions are welcome?

• Documents

  • The current directory structure reflects our wishlist. If you can help with one of those, that’s fantastic.
  • You may also add a document not on the list, even of in a new category that you feel would benefit our students or coaches.
  • We believe many ClojureBridge workshops will be organized all over the world for years to come, and we welcome new documents at anytime.
    
    

• Suggestions

  • We appreciate your suggestions about lab topics, document structure, or even about using Github pages.
  • You will probably notice many gaps after attending ClojureBridge workshop.
  • Please help us improve by opening a new issue.
    
    

• Corrections

  • Absolutely welcome. We welcome your pull requests.
  • Even small changes (correcting errors, clearing up confusing explanations, etc.) are important.
    
    

• Design Love

  • LOVE! We would really appreciate contributions in this area.

When you want to say something about a document…

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!