_content/doc: convert most release notes to Markdown

Add Markdown conversions for all release notes except the first to the
content for the go.dev site. Because the site prefers .md to .html
files, these files will be served even though the .html files still

This CL omits the first release notes file (go1.html) because it is a
template. None of the others need template expansion. We will convert
go1.html in a followup CL.

The goal in this CL was to minimize diffs. We compared the rendering
of each Markdown file with the live site using cmd/screentest
to make sure there were no major differences. Later CLs can make
changes to the formatting, for example by replacing definition
lists with level-4 headings, but we found it was easier to find
serious conversion issues this way.

To get the diffs, run
    go run ./cmd/screentest ./cmd/screentest/testdata/relnotes.txt
from the repo root.

Some diffs still exist:

- The Markdown renderer used by the site replaces characters like "
  and ' with their "fancier" forms outside of code. The original HTML
  files used the ASCII characters. Most of the differences are due
  to this.

- The Markdown renderer expands tabs to 4 spaces, where the browser
  (at least Chrome) formats them with 8. The difference can be
  seen in code blocks (which look better in Markdown).

- In go1.18, there is a very slight bit of extra space in the HTML
  that produces what looks like a large diff. There was no easy
  way to fix the spacing.

We converted the files using a slightly modified version of
github.com/rsc/tmp/html2md. We then sometimes hand-edited the files
when it didn't seem worth writing code to address the diff.

We had to change the "id" attribute for a heading in seven places,
because the attribute value contained a '/' or ' ' and the Markdown
renderer doesn't accept "id"s with those characters. We replaced the
offending characters with '_'. The change means that if we deploy
from this CL, links to those headings will break temporarily. Fixing
this now would involve forking all or a part of Goldmark, and we have
a better solution. Russ Cox has written a much smaller and simpler
markdown parser and renderer. Since we control it, we can have it
handle "id" attributes with spaces and slashes. We will replace
Goldmark with it eventually. But first we have to replace definition
lists with headings, because Russ's parser doesn't handle definition
lists. (None of the other Markdown files on the site use them.)

For reference, the altered heading IDs are:

- go1.13: crypto/ed25519
- go1.14: hash/maphash
- go1.15: time/tzdata
- go1.17: runtime/cgo
- go1.17: go run
- go1.18: debug/buildinfo
- go1.20: crypto/ecdh

Change-Id: Ibe02c8af2604908c3fd47a9674a4df01b128ff57
Reviewed-on: https://go-review.googlesource.com/c/website/+/539755
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Heschi Kreinick <heschi@google.com>
21 files changed
tree: bf1d1b9c8a5c72798b50ff776e30115101d8a1c2
  1. _content/
  2. _later/
  3. cmd/
  4. internal/
  5. tour/
  6. .eslintrc.yaml
  7. .gitattributes
  8. .prettierrc.yaml
  9. .stylelintrc.yaml
  10. codereview.cfg
  11. content.go
  13. go-app-deploy.sh
  14. go.mod
  15. go.sum
  16. jest-transform.cjs
  18. npm
  19. npx
  20. package-lock.json
  21. package.json
  23. README.md
  24. tsconfig.json

Go website

Go Reference

This repo holds content and serving programs for the go.dev and golang.org web sites.

Content is in _content/ (go.dev) and tour/ (go.dev/tour). Server code is in cmd/ and internal/.

To run the combined go.dev+golang.org server to preview local content changes, use:

go run ./cmd/golangorg

The supporting programs cmd/admingolangorg and cmd/googlegolangorg are the servers for admin.golang.org and google.golang.org. (They do not use the _content/ directories.)

Each command directory has its own README.md explaining deployment.

JS/TS/CSS Formatting

This repository uses eslint to format JS and TS files, and stylelint to format CSS files.

See also:

It is encouraged that all JS, TS, and CSS code be run through formatters before submitting a change. However, it is not a strict requirement enforced by CI.

Installing npm Dependencies:

  1. Install docker
  2. Create a .gitignore file at repo root
  3. Add .gitignore and node_modules to .gitignore
  4. Run ./npm install

Run ESlint

./npx eslint [options] [file] [dir]

Run Stylelint

./npx stylelint [input] [options]

TypeScript Support

TypeScript files served from _content are transformed into JavaScript. Reference .ts files in html templates as module code.

<script type="module" src="/ts/filename.ts">

Write unit tests for TypeScript code using the jest testing framework.

Run Jest

./npx jest [TestPathPattern]


Each time a CL is reviewed and submitted, the code is deployed to App Engine. See cmd/golangorg/README.md for details.

Report Issues / Send Patches

This repository uses Gerrit for code changes. To learn how to submit changes to this repository, see https://go.dev/doc/contribute.

The main issue tracker for the website repository is located at https://github.com/golang/go/issues. Prefix your issue with “x/website:” in the subject line, so it is easy to find.