tree bf1d1b9c8a5c72798b50ff776e30115101d8a1c2
parent 12c78e6028971ce526b8076baa5f94439337c16b
author Jonathan Amsterdam <jba@google.com> 1699049080 -0400
committer Jonathan Amsterdam <jba@google.com> 1699888295 +0000

_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
exist.

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>