Skip to content

Commit

Permalink
_content/doc: convert most release notes to Markdown
Browse files Browse the repository at this point in the history
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 <[email protected]>
Run-TryBot: Jonathan Amsterdam <[email protected]>
Reviewed-by: Heschi Kreinick <[email protected]>
  • Loading branch information
jba committed Nov 13, 2023
1 parent 12c78e6 commit df570c7
Show file tree
Hide file tree
Showing 21 changed files with 19,358 additions and 0 deletions.
805 changes: 805 additions & 0 deletions _content/doc/go1.1.md

Large diffs are not rendered by default.

1,123 changes: 1,123 additions & 0 deletions _content/doc/go1.10.md

Large diffs are not rendered by default.

809 changes: 809 additions & 0 deletions _content/doc/go1.11.md

Large diffs are not rendered by default.

826 changes: 826 additions & 0 deletions _content/doc/go1.12.md

Large diffs are not rendered by default.

911 changes: 911 additions & 0 deletions _content/doc/go1.13.md

Large diffs are not rendered by default.

807 changes: 807 additions & 0 deletions _content/doc/go1.14.md

Large diffs are not rendered by default.

911 changes: 911 additions & 0 deletions _content/doc/go1.15.md

Large diffs are not rendered by default.

1,090 changes: 1,090 additions & 0 deletions _content/doc/go1.16.md

Large diffs are not rendered by default.

1,095 changes: 1,095 additions & 0 deletions _content/doc/go1.17.md

Large diffs are not rendered by default.

1,200 changes: 1,200 additions & 0 deletions _content/doc/go1.18.md

Large diffs are not rendered by default.

991 changes: 991 additions & 0 deletions _content/doc/go1.19.md

Large diffs are not rendered by default.

680 changes: 680 additions & 0 deletions _content/doc/go1.2.md

Large diffs are not rendered by default.

1,146 changes: 1,146 additions & 0 deletions _content/doc/go1.20.md

Large diffs are not rendered by default.

1,177 changes: 1,177 additions & 0 deletions _content/doc/go1.21.md

Large diffs are not rendered by default.

432 changes: 432 additions & 0 deletions _content/doc/go1.3.md

Large diffs are not rendered by default.

625 changes: 625 additions & 0 deletions _content/doc/go1.4.md

Large diffs are not rendered by default.

900 changes: 900 additions & 0 deletions _content/doc/go1.5.md

Large diffs are not rendered by default.

691 changes: 691 additions & 0 deletions _content/doc/go1.6.md

Large diffs are not rendered by default.

943 changes: 943 additions & 0 deletions _content/doc/go1.7.md

Large diffs are not rendered by default.

1,317 changes: 1,317 additions & 0 deletions _content/doc/go1.8.md

Large diffs are not rendered by default.

879 changes: 879 additions & 0 deletions _content/doc/go1.9.md

Large diffs are not rendered by default.

0 comments on commit df570c7

Please sign in to comment.