Skip to content

superorbital/golangcookbook.github.io

Repository files navigation

Go Cookbook

Source for the Go Cookbook, a community built collection of practical recipes and contributions for real world Golang development, supported by SuperOrbital.

Contributing

The Go Cookbook is supported by SuperOrbital, but built by the community, so your contributions are very welcome. Just send a pull request for any changes or additions.

Adding a New Recipe

Recipes are generated from the _data/chapters.yml file, which is used to build the index page. The chapters.yml file format is:

- title: Strings
  recipes:
  - title: Concatenating Strings
    path: /chapters/strings/concatenation
    wip: true
  - title: Detecting a Substring
    path: /chapters/strings/detecting
  - title: Detecting All Substrings
    path: false

Specifying wip: true puts "[Work in progress]" in front of the recipe in the index. Setting path: false causes the recipe to be listed without a link.

Recipe Format

Recipe files have a couple of required properties, specified in the preamble like such:

---
title: Processing a String One Word or Character at a Time
question: Given a string, how do I break it into words or characters and process each one in turn?
---

Also, to show example code, recipes can make use of the {% include example.html example="filename" %} helper. This will include both filename.go as example source code, and filename.expected.escaped as the output of that code. If you're curious, here's the definition for that helper. The filename.expected.escaped files are automatically generated by the ./run_tests script, described below.

Run locally

This project uses Docker for local development. Once you have Docker installed:

$ ./run server
$ open http://localhost:4000

Run the tests

$ ./run tests

The run_tests script runs the tests and ensures the .expected, .go.escaped, and .expected.escaped files are in place. These files are used in the recipe templates to ensure all examples are up to date and correct.

License

Creative Commons License

The Go Cookbook copyright SuperOrbital, and is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.