save

Author: jcbhmr

content/en/_index.md

@@ -1,5 +1,42 @@
----
-weight: 1
----
+# Go by Example
 
-Hello world
+[Go](https://go.dev/) is an open-source programming language designed for building scalable, secure, and reliable software. Please read the [official documentation](https://go.dev/doc/tutorial/getting-started) to learn more.
+
+*Go by Example* is a hands-on introduction to Go using annotated example programs. Check out the [first example](hello-world.md) or browse the full list below.
+
+Unless stated otherwise, the examples here assume the [latest major release Go](https://go.dev/doc/devel/release) and may use new language features. If something isn't working, try upgrading to the latest version.
+
+{{< docstoc >}}
+
+### FAQ
+
+#### I found a problem with the examples; what do I do?
+
+We're very happy to fix problem reports and accept contributions! Please submit
+[an issue](https://github.com/jcbhmt/gobyexample.jcbhmr.com/issues) or send a Pull Request.
+See `CONTRIBUTING.md` for more details.
+
+#### What version of Go is required to run these examples?
+
+Given Go's strong [backwards compatibility guarantees](https://go.dev/doc/go1compat),
+we expect the vast majority of examples to work on the latest released version of Go
+as well as many older releases going back years.
+
+That said, some examples show off new features added in recent releases; therefore,
+it's recommended to try running examples with the latest officially released Go version
+(see Go's [release history](https://go.dev/doc/devel/release) for details).
+
+#### I'm getting output in a different order from the example. Is the example wrong?
+
+Some of the examples demonstrate concurrent code which has a non-deterministic
+execution order. It depends on how the Go runtime schedules its goroutines and
+may vary by operating system, CPU architecture, or even Go version.
+
+Similarly, examples that iterate over maps may produce items in a different order
+from what you're getting on your machine. This is because the order of iteration
+over maps in Go is [not specified and is not guaranteed to be the same from one
+iteration to the next](https://go.dev/ref/spec#RangeClause).
+
+It doesn't mean anything is wrong with the example. Typically the code in these
+examples will be insensitive to the actual order of the output; if the code is
+sensitive to the order - that's probably a bug - so feel free to report it.

content/en/docs/README.md

@@ -1,9 +1,3 @@
-# Summary
-
-[Go by Example](README.md)
-
----
-
 - [Hello World](hello-world.md)
 - [Values](values.md)
 - [Variables](variables.md)

content/en/docs/SUMMARY.md renamed to content/en/docs/SUMMARY.txt

@@ -1,47 +1,66 @@
+---
+weight: 4
+---
+
 # Constants
 
-```go,editable
-// Go supports _constants_ of character, string, boolean,
-// and numeric values.
+Go supports _constants_ of character, string, boolean,
+and numeric values.
+
+`const` declares a constant value.
 
+```go
 package main
 
-import (
-	"fmt"
-	"math"
-)
+import "fmt"
 
-// `const` declares a constant value.
 const s string = "constant"
 
 func main() {
 	fmt.Println(s)
+	// Output: constant
+}
+```
+
+A `const` statement can appear anywhere a `var`
+statement can.
+
+```go
+package main
 
-	// A `const` statement can appear anywhere a `var`
-	// statement can.
+func main() {
 	const n = 500000000
+	fmt.Println(n)
+	// Output: 500000000
+}
+```
 
-	// Constant expressions perform arithmetic with
-	// arbitrary precision.
-	const d = 3e20 / n
-	fmt.Println(d)
+Constant expressions perform arithmetic with
+arbitrary precision.
 
-	// A numeric constant has no type until it's given
-	// one, such as by an explicit conversion.
-	fmt.Println(int64(d))
+```go
+const n = 500000000
+const d = 3e20 / n
+fmt.Println(d)
+// Output: 6e+11
+```
 
-	// A number can be given a type by using it in a
-	// context that requires one, such as a variable
-	// assignment or function call. For example, here
-	// `math.Sin` expects a `float64`.
-	fmt.Println(math.Sin(n))
-}
+A numeric constant has no type until it's given
+one, such as by an explicit conversion.
+
+```go
+const d = 6e+11
+fmt.Println(int64(d))
+// Output: 600000000000
 ```
 
-```sh
-$ go run constant.go
-constant
-6e+11
-600000000000
--0.28470407323754404
+A number can be given a type by using it in a
+context that requires one, such as a variable
+assignment or function call. For example, here
+`math.Sin` expects a `float64`.
+
+```go
+const n = 500000000
+fmt.Println(math.Sin(n))
+// Output: -0.28470407323754404
 ```

content/en/docs/constants.md

@@ -1,69 +1,79 @@
+---
+weight: 5
+---
+
 # For
 
-```go,editable
-// `for` is Go's only looping construct. Here are
-// some basic types of `for` loops.
+`for` is Go's only looping construct. Here are
+some basic types of `for` loops.
 
-package main
+The most basic type, with a single condition.
 
-import "fmt"
+```go
+i := 1
+for i <= 3 {
+	fmt.Println(i)
+	i = i + 1
+}
+// Output:
+// 1
+// 2
+// 3
+```
 
-func main() {
+A classic initial/condition/after `for` loop.
 
-	// The most basic type, with a single condition.
-	i := 1
-	for i <= 3 {
-		fmt.Println(i)
-		i = i + 1
-	}
+```go
+for j := 0; j < 3; j++ {
+	fmt.Println(j)
+}
+// Output:
+// 0
+// 1
+// 2
+```
 
-	// A classic initial/condition/after `for` loop.
-	for j := 0; j < 3; j++ {
-		fmt.Println(j)
-	}
+Another way of accomplishing the basic "do this
+N times" iteration is `range` over an integer.
 
-	// Another way of accomplishing the basic "do this
-	// N times" iteration is `range` over an integer.
-	for i := range 3 {
-		fmt.Println("range", i)
-	}
+```go
+for i := range 3 {
+	fmt.Println("range", i)
+}
+// Output:
+// range 0
+// range 1
+// range 2
+```
 
-	// `for` without a condition will loop repeatedly
-	// until you `break` out of the loop or `return` from
-	// the enclosing function.
-	for {
-		fmt.Println("loop")
-		break
-	}
+`for` without a condition will loop repeatedly
+until you `break` out of the loop or `return` from
+the enclosing function.
 
-	// You can also `continue` to the next iteration of
-	// the loop.
-	for n := range 6 {
-		if n%2 == 0 {
-			continue
-		}
-		fmt.Println(n)
-	}
+```go
+for {
+	fmt.Println("loop")
+	break
 }
+// Output: loop
 ```
 
-```sh
-$ go run for.go
-1
-2
-3
-0
-1
-2
-range 0
-range 1
-range 2
-loop
-1
-3
-5
+You can also `continue` to the next iteration of
+the loop.
 
-# We'll see some other `for` forms later when we look at
-# `range` statements, channels, and other data
-# structures.
+```go
+for n := range 6 {
+	if n%2 == 0 {
+		continue
+	}
+	fmt.Println(n)
+}
+// Output:
+// 1
+// 3
+// 5
 ```
+
+We'll see some other `for` forms later when we look at
+`range` statements, channels, and other data
+structures.

content/en/docs/for.md

@@ -1,8 +1,15 @@
+---
+weight: 1
+---
+
 # Hello World
 
-```go,editable
-// Our first program will print the classic "hello world"
-// message. Here's the full source code.
+Our first program will print the classic "hello world"
+message. Here's the full source code.
+
+{{% goplay %}}
+
+```go
 package main
 
 import "fmt"
@@ -12,22 +19,31 @@ func main() {
 }
 ```
 
+{{% /goplay %}}
+
+To run the program, put the code in `hello-world.go` and
+use `go run`.
+
 ```sh
-# To run the program, put the code in `hello-world.go` and
-# use `go run`.
 $ go run hello-world.go
 hello world
+```
+
+Sometimes we'll want to build our programs into
+binaries. We can do this using `go build`.
 
-# Sometimes we'll want to build our programs into
-# binaries. We can do this using `go build`.
+```sh
 $ go build hello-world.go
 $ ls
 hello-world	hello-world.go
+```
+
+We can then execute the built binary directly.
 
-# We can then execute the built binary directly.
+```sh
 $ ./hello-world
 hello world
-
-# Now that we can run and build basic Go programs, let's
-# learn more about the language.
 ```
+
+Now that we can run and build basic Go programs, let's
+learn more about the language.