content: update README
The README does not mention that files that are newly added to
the content directory need to be added manually to static/gen.go
file before running go generate. This change fixes that.
Update the description of how the static content is used in concert
with the content from the main Go repository in more detail.
Replace go install && ./golangorg with go run, since it's shorter.
Add a TODO note mentioning improvements that can be made in the near
future to simplify this process.
Updates golang/go#29206
Change-Id: I8a85bcb783c7c10975aa6fd5a7ad464f05d42dd2
Reviewed-on: https://go-review.googlesource.com/c/website/+/207262
Reviewed-by: Andrew Bonventre <andybons@golang.org>
diff --git a/content/README.md b/content/README.md
index 692f5eb..05cd1be 100644
--- a/content/README.md
+++ b/content/README.md
@@ -1,11 +1,17 @@
# content
-This directory contains doc/, static/, favicon.ico, and robots.txt. The
-executable lives at golang.org/x/website/cmd/golangorg.
+The `static` directory contains static content. This content is used alongside
+the content in the main Go repository by the [`golangorg`](golang.org/x/website/cmd/golangorg)
+binary when serving the [golang.org](https://golang.org) website.
+The details of the directory to path mapping are documented at the top of
+[`cmd/golangorg/main.go`](https://go.googlesource.com/website/+/refs/heads/master/cmd/golangorg/main.go).
+
+TODO(dmitshur): The process below can be simplified.
+See [golang.org/issue/29206#issuecomment-536099768](https://golang.org/issue/29206#issuecomment-536099768).
## Development mode
-In production, CSS/JS/template assets need to be compiled into the golangorg
+In production, CSS/JS/template assets need to be compiled into the `golangorg`
binary. It can be tedious to recompile assets every time, but you can pass a
flag to load CSS/JS/templates from disk every time a page loads:
@@ -15,16 +21,31 @@
## Recompiling static assets
-The files that live at `static/style.css`, `static/jquery.js` and so on are not
-present in the final binary. They are placed into `static/static.go` by running
-`go generate`. So to compile a change and test it in your browser:
+Files such as `static/style.css`, `static/doc/copyright.html` and so on are not
+present in the final binary. They are embedded into `static/static.go` by running
+`go generate`. To compile a change and test it in your browser:
-1) Make changes to e.g. `static/style.css`.
+1) Make changes to an existing file such as `static/style.css`.
-2) Run `go generate golang.org/x/website/content/static` so `static/static.go` picks
-up the change.
+2) If a new file is being added to the `static` directory, add it to the `files`
+slice in `static/gen`.
-3) Run `go install golang.org/x/website/cmd/golangorg` so the compiled `golangorg` binary picks up the change.
+3) Run `go generate golang.org/x/website/content/static` so `static/static.go` is
+up to date.
-4) Run `golangorg -http=:6060` and view your changes in the browser. You may need
-to disable your browser's cache to avoid reloading a stale file.
+4) Run `go run golang.org/x/website/cmd/golangorg -http=:6060` and view your changes
+in the browser at http://localhost:6060. You may need to disable your browser's cache
+to avoid reloading a stale file.
+
+A test exists to catch a possible mistake of forgetting to regenerate static assets:
+
+```
+website $ go test ./...
+--- FAIL: TestStaticIsUpToDate (0.06s)
+ gen_test.go:27: static.go is stale. Run:
+ $ go generate golang.org/x/website/content/static
+ $ git diff
+ to see the differences.
+FAIL
+FAIL golang.org/x/website/content/static 0.650s
+```
