wiki: clean up markdown

Normalized heading levels, updated titles, fixed a few link syntax problems. We might delete some of these as outdated at some point. For golang/go#61940.
golang · Dec 5, 2023 · 270a22d · 270a22d
1 parent acff1b5
commit 270a22d
Show file tree

Hide file tree

Showing 157 changed files with 1,668 additions and 1,067 deletions.
diff --git a/AVX512.md b/AVX512.md
@@ -1,3 +1,7 @@
+---
+title: AVX512
+---
+
 Go 1.11 release introduces [AVX-512](https://en.wikipedia.org/wiki/AVX-512) support.  
 This page describes how to use new features as well as some important encoder details.
 
@@ -284,4 +288,4 @@ noConflicts:
         ADDL        $16, DX            //; add         edx, 0x10
         CMPL        DX, $1024          //; cmp         edx, 0x400
         JB          top                //; jb          top
-```
+```
diff --git a/Articles.md b/Articles.md
@@ -1,3 +1,7 @@
+---
+title: Articles
+---
+
 
 Please keep all entries in reverse chronological order (most recent first)
 
@@ -261,4 +265,4 @@ Start by reading the [overview of server programming](LearnServerProgramming) do
   * [Go: 90% 완벽?!, 100% of the time 슬라이드 번역 ](http://100coding.com/go/slide)
   * [Go 동시성 패턴 advanced 영상 번역](http://www.youtube.com/watch?v=4g2skln42eo)
   * [Go + Revel + Gorp 간단 게시판 만들기](http://100coding.com/go/tutorial/1)
-  * [Go + Revel + Gorm 으로 만드는 블로그](https://github.com/jaehue/goblog/wiki/Hello-World)
+  * [Go + Revel + Gorm 으로 만드는 블로그](https://github.com/jaehue/goblog/wiki/Hello-World)
diff --git a/AssemblyPolicy.md b/AssemblyPolicy.md
@@ -1,3 +1,7 @@
+---
+title: AssemblyPolicy
+---
+
 This document describes when and how to add assembly code to the Go cryptography packages.
 
 In general, the rules are:
@@ -12,4 +16,4 @@ In general, the rules are:
 * The code must be tested in our CI. This means there need to be builders that support the instructions, and if there are multiple (or fallback) paths they must be tested separately. (Tip: use `GODEBUG=cpu.X=off` to disable detection of CPU features.)
 * Document in the Go code why the implementation requires assembly (specific performance benefit, access to instructions, etc), so we can reevaluate as the compiler improves.
 
-Not all assembly currently in the standard library adheres to this policy. Changes to existing assembly will be discouraged until that implementation is updated to be compliant. New assembly must be compliant.
+Not all assembly currently in the standard library adheres to this policy. Changes to existing assembly will be discouraged until that implementation is updated to be compliant. New assembly must be compliant.
diff --git a/Benchmarks.md b/Benchmarks.md
@@ -1,3 +1,7 @@
+---
+title: Benchmarks
+---
+
 These are benchmarks collected from the community used to measure the effects of changes to the Go core (compiler, runtime, garbage collector, and libraries). They should have the following properties:
 
  - they matter; someone cares, perhaps in a dollars-and-cents way, that they run well
@@ -65,3 +69,4 @@ A few have been proposed but have so far failed to make the cut (for fetch, buil
  | eolian_dsp | | `buddin.us/eolian/dsp` | `Benchmark` | |
  | ethereum_whisperv5 | | `github.com/ethereum/go-ethereum/whisper/whisperv5` | `Benchmark` | |
  | kanzi | | `github.com/flanglet/kanzi/go/src/kanzi/benchmark` | `Benchmark` | |
+
diff --git a/Blogs.md b/Blogs.md
@@ -1,3 +1,7 @@
+---
+title: Blogs
+---
+
 A set of blogs dedicated to Go.
 
 NOTE: Please don't add individual blog entries to this page. Those belong in [articles](Articles) instead.
@@ -84,3 +88,4 @@ NOTE: Please don't add individual blog entries to this page. Those belong in [ar
 * [No Headback](http://xargin.com/)
 * [Go 语言基础](https://github.com/weirubo/learn_go)
 * [chai2010 的博客](https://chai2010.cn/)
+
diff --git a/Books.md b/Books.md
@@ -1,3 +1,7 @@
+---
+title: Books
+---
+
 Other book lists:
 
 * [Awesome Go Books](https://github.com/dariubs/GoBooks)
@@ -21,7 +25,7 @@ Sorted by publication date, ascending.
 - [Polish](#polish)
 - [Persian](#persian)
 
-# English
+### English
   * **Go Programming**
     * Author: John P. Baugh
     * Publication Date: June 16, 2010
@@ -664,7 +668,7 @@ Sorted by publication date, ascending.
     * Reference: http://microservicesingo.com/
     * Status: [Cancelled per O'Reilly Employee](http://support.oreilly.com/oreilly/topics/availability-of-microservices-in-go-use-go-to-build-scalable-backends-by-matthew-campbell)
 
-# Chinese
+### Chinese
   * **Go语言·云动力**
     * Author: 樊虹剑（fango）
     * Publication Date: 2012-06
@@ -734,7 +738,7 @@ Sorted by publication date, ascending.
     * ISBN: ---
     * Reference: https://github.com/chai2010/ugo-compiler-book
 
-# Japanese
+### Japanese
   * **はじめての「Go言語」**
     * Author: 茨木 隆彰
     * Publication Date: 2010-11
@@ -801,7 +805,7 @@ Sorted by publication date, ascending.
     * ISBN: 978-4297134198
     * Reference: https://gihyo.jp/book/2023/978-4-297-13419-8
 
-# French
+### French
 
   * **Programmer en Go - Pourquoi ? Comment ?**
     * Author: Rudy Rigot
@@ -817,7 +821,7 @@ Sorted by publication date, ascending.
     * Reference (publisher): https://www.dunod.com/sciences-techniques/langage-go-fondamentaux-du-langage
 
 
-# German
+### German
   * **Programmierung in Google Go** (not available for buying any more)
     * Authors: Rainer Feike and Steffen Blass
     * Publication Date: 2010-11
@@ -843,7 +847,7 @@ Sorted by publication date, ascending.
     * ISBN: 978-3-86802-415-9
     * Reference: http://entwickler.de/press/Einstieg-in-Google-Go
 
-# Brazilian Portuguese
+### Brazilian Portuguese
   * **A Linguagem de Programação Go**
     * Author:  Alan A. A. Donovan, Brian W. Kernighan 
     * Publication Date: 2017
@@ -862,7 +866,7 @@ Sorted by publication date, ascending.
     * ISBN: 978-85-75224-89-2
     * Reference: http://shop.oreilly.com/product/0636920046516.do
 
-# Russian
+### Russian
   * **Программирование на языке Go**
     * Author: Марк Саммерфильд
     * Publication Date: 2013-02-14
@@ -887,7 +891,7 @@ Sorted by publication date, ascending.
     * ISBN: 978-5-4461-1617-1
     * Reference: https://www.piter.com/product/golang-dlya-profi-rabota-s-setyu-mnogopotochnost-struktury-dannyh-i-mashinnoe-obuchenie-s-go
 
-# Español
+### Español
   * **Aprende Go en Y minutos**https://go101.org
     * Author: Nacho Pacheco
     * Publication Date: 2015-02-24
@@ -906,7 +910,7 @@ Sorted by publication date, ascending.
     * ISBN: ---
     * Reference: https://www.gitbook.com/book/nachopacheco/go-es/
 
-# Korean
+### Korean
   * **가장 빨리 만나는 Go 언어**
     * Author: 이재홍
     * Publication Date: June 2015
@@ -985,7 +989,7 @@ Sorted by publication date, ascending.
     * ISBN: 979-1-16175-208-2
     * Reference: http://acornpub.co.kr/book/mastering-go
 
-# Indonesian
+### Indonesian
   * **Bahasa Pemrograman Go**
     * Author: Sajarwo Anggai
     * Publication Date: October 21, 2013
@@ -998,7 +1002,7 @@ Sorted by publication date, ascending.
     * ISBN: ---
     * Reference: https://dasarpemrogramangolang.novalagung.com
 
-# Italian
+### Italian
   * **Programmare in Linguaggio Go**
     * Author: Renato Mite
     * Publication Date: 9 Oct 2016
@@ -1008,15 +1012,15 @@ Sorted by publication date, ascending.
     * Reference (Kobo Books): https://store.kobobooks.com/it-it/ebook/programmare-in-linguaggio-go
     * Repository: https://github.com/rmite/gobook
 
-# Polish
+### Polish
 
   * **Język Go. Poznaj i programuj**
     * Authors: Alan A. A. Donovan, Brian W. Kernighan; translated by Lech Lachowski
     * Publication Date: July 2016
     * ISBN: 978-83-283-2467-1
     * Reference: https://helion.pl/ksiazki/jezyk-go-poznaj-i-programuj-alan-a-a-donovan-brian-w-kernighan,jgopop.htm
 
-# Persian
+### Persian
   * **GoFarsi book**
     * Author: Javad Rajabzadeh
     * Publication Date: 23 oct 2022
@@ -1030,7 +1034,7 @@ Sorted by publication date, ascending.
     * ISBN: ---
     * Repository: https://github.com/thedevsir/gosuccinctly
 
-# Looking for contributors
+### Looking for contributors
 
 [Add Go books here that are looking for writers, editors, Gopher illustrators, and translators.]
 
@@ -1040,4 +1044,3 @@ Sorted by publication date, ascending.
     * ISBN: 9781787286740
     * Reference: https://www.amazon.in/Web-Development-Cookbook-full-stack-applications/dp/1787286746
 
-***
diff --git a/BoundingResourceUse.md b/BoundingResourceUse.md
@@ -1,3 +1,7 @@
+---
+title: Bounding resource use
+---
+
 To bound a program's use of a limited resource - like memory - have goroutines synchronize their use of that resource using a buffered channel (i.e., use the channel as a semaphore):
 
 ```go
@@ -25,4 +29,5 @@ func handle(r *Request) {
 
 ## References
 
-Effective Go's discussion of channels: https://go.dev/doc/effective_go#channels
+Effective Go's discussion of channels: https://go.dev/doc/effective_go#channels
+
diff --git a/CSSStyleGuide.md b/CSSStyleGuide.md
@@ -1,4 +1,6 @@
-# Go CSS Coding Guidelines
+---
+title: Go CSS Coding Guidelines
+---
 
 **Please [discuss changes](https://go.dev/issue/new?title=wiki%3A+CSSStyleGuide+change&body=&labels=Documentation) before editing this page**, even _minor_ ones. Many people have opinions and this is not the place for edit wars.
 
@@ -218,3 +220,5 @@ Add height and width attributes to images in the html markup to help minimize la
 ```
 <img src="url/to/image.png" height="240" width="160">
 ```
+
+
diff --git a/ChromeOS.md b/ChromeOS.md
@@ -1,4 +1,8 @@
-# Introduction
+---
+title: ChromeOS
+---
+
+## Introduction
 
 You don't need to compile from source in Developer mode, you can just use the [Chromebrew](https://github.com/skycocker/chromebrew)-provided version.
 
@@ -7,7 +11,7 @@ If your Chromebook is relatively new, you can enable the Linux VM now built into
 This tutorial will show you how to install, build, and run Go on Chrome OS.
 Please note this has only been tested on a 64GB LTE Pixel, however it should work on other Chromebooks. Note that enabling developer mode reduces the security guarantees offered by Chrome OS.
 
-# Install Go
+## Install Go
 First download the latest version of Go for Linux from the [Go Downloads page](https://go.dev/dl/).
 After that, open a shell by hitting (CTRL+ALT+T) and typing in `shell` then hit enter. Then extract it using the following command (when replacing `< Go Linux package >` with the name of the file you downloaded):
 
@@ -17,18 +21,18 @@ sudo tar xpvf ~/Downloads/< Go Linux package > -C /usr/local
 
 Go should now be installed you can test this by typing `/usr/local/go/bin/go`. If it installed correctly, you should see the Go help prompt. Go is now installed.
 
-# Create a Workspace
+## Create a Workspace
 To keep this simple just create a folder called `/usr/local/go/work`. Also, create a folder called `src` inside `/usr/local/go/work/`.
 
-# Set PATH
+## Set PATH
 Add the following to `~/.bashrc`:
 ```
 export GOPATH="/usr/local/go/work"
 export PATH="${PATH}:/usr/local/go/bin:${GOPATH}/bin"
 ```
 This will allow you to run your Go programs in your shell.
 
-# Test if it worked
+## Test if it worked
 First create a folder inside of your `/usr/local/go/src` folder. After that create a file in your folder called `hello.go` with the following in it:
 ```go
 package main
@@ -42,5 +46,7 @@ func main() {
 Now, run `go install hello`. Then, run `${GOPATH}/bin/hello` (or just `hello` if you setup your GOPATH above) and you should see `Hello, Chrome OS!`.
 ***
 
-# Reporting bugs
+## Reporting bugs
 Please go to [Issues](https://github.com/golang/go/issues) to report any issues you have.
+
+
diff --git a/CodeReview.md b/CodeReview.md
@@ -1,3 +1,7 @@
+---
+title: CodeReview
+---
+
 Be sure to familiarize yourself with the code review process from the official [Contribution Guide](https://go.dev/doc/contribute) first.
 
 # Reviewer Parlance
@@ -51,4 +55,4 @@ Gerrit's code review model is to rewrite a single commit until it is correct. Gi
 $ git remote add --mirror=push fork [email protected]:yourusername/go.git
 ```
 
-Then running `git push fork` will update GitHub to perfectly mirror *everything* (all branches, all tags, etc.). This is handy, but take care when using this on multiple clients. You are bypassing the usual git safeguards, so it is easy to overwrite (and thus lose) work pushed by a different client.
+Then running `git push fork` will update GitHub to perfectly mirror *everything* (all branches, all tags, etc.). This is handy, but take care when using this on multiple clients. You are bypassing the usual git safeguards, so it is easy to overwrite (and thus lose) work pushed by a different client.
diff --git a/CodeReviewComments.md b/CodeReviewComments.md
@@ -1,12 +1,14 @@
-# Go Code Review Comments
+---
+title: Go Code Review Comments
+---
 
 This page collects common comments made during reviews of Go code, so
 that a single detailed explanation can be referred to by shorthands.
 This is a laundry list of common style issues, not a comprehensive style guide.
 
 You can view this as a supplement to [Effective Go](https://go.dev/doc/effective_go).
 
-Additional comments related to testing can be found at [Go Test Comments](https://github.com/golang/go/wiki/TestComments)
+Additional comments related to testing can be found at [Go Test Comments](/wiki/TestComments)
 
 Google has published a longer [Go Style Guide](https://google.github.io/styleguide/go/decisions).
 
@@ -425,7 +427,7 @@ boundaries are, not to start counting lines.
 
 See https://go.dev/doc/effective_go#mixed-caps. This applies even when it breaks conventions in other languages. For example an unexported constant is `maxLength` not `MaxLength` or `MAX_LENGTH`.
 
-Also see [Initialisms](https://github.com/golang/go/wiki/CodeReviewComments#initialisms).
+Also see [Initialisms](/wiki/CodeReviewComments#initialisms).
 
 ## Named Result Parameters
 
@@ -597,7 +599,7 @@ if got != tt.want {
 
 Note that the order here is actual != expected, and the message uses that order too. Some test frameworks encourage writing these backwards: 0 != x, "expected 0, got x", and so on. Go does not.
 
-If that seems like a lot of typing, you may want to write a [[table-driven test|TableDrivenTests]].
+If that seems like a lot of typing, you may want to write a [table-driven test](TableDrivenTests).
 
 Another common technique to disambiguate failing tests when using a test helper with different input is to wrap each caller with a different TestFoo function, so the test fails with that name:
 
@@ -615,3 +617,5 @@ Variable names in Go should be short rather than long.  This is especially true
 The basic rule: the further from its declaration that a name is used, the more descriptive the name must be. For a method receiver, one or two letters is sufficient. Common variables such as loop indices and readers can be a single letter (`i`, `r`). More unusual things and global variables need more descriptive names.
 
 See also the longer discussion in [the Google Go Style Guide](https://google.github.io/styleguide/go/decisions#variable-names).
+
+
diff --git a/CodeReviewConcurrency.md b/CodeReviewConcurrency.md
@@ -1,7 +1,9 @@
-# Code Review: Go Concurrency
+---
+title: "Code Review: Go Concurrency"
+---
 
 This page is an addition to the [Go Code Review Comments](
-https://github.com/golang/go/wiki/CodeReviewComments) list. The goal of this list is to help to find
+/wiki/CodeReviewComments) list. The goal of this list is to help to find
 concurrency-related bugs when reviewing Go code.
 
 You may also read through this list just once to refresh your memory and to make sure you are aware
@@ -126,7 +128,7 @@ same result and doesn't have side effects.
 
 If the race condition is not benign, use methods [`sync.Map.LoadOrStore()`](
 https://pkg.go.dev/sync/#Map.LoadOrStore) and [`LoadAndDelete()`](
-https://pkg.go.dev/sync/#Map.LoadAndDelete) to fix it. 
+https://pkg.go.dev/sync/#Map.LoadAndDelete) to fix it.
 
 ### Scalability
 
@@ -227,7 +229,7 @@ This code would be wrong without calling `Round(0)`, i. e. stripping the monoton
 
 ## Reading List
 
-[Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments): a checklist for
+[Go Code Review Comments](/wiki/CodeReviewComments): a checklist for
 reviewing Go code, not concurrency-specific.
 
 Go concurrency:
@@ -245,4 +247,5 @@ Go concurrency:
 
 Concurrency, but not specific to Go:
  - [Mechanical Sympathy: Single Writer Principle](
-   https://mechanical-sympathy.blogspot.com/2011/09/single-writer-principle.html)
+   https://mechanical-sympathy.blogspot.com/2011/09/single-writer-principle.html)
+
diff --git a/CodeTools.md b/CodeTools.md
@@ -1,3 +1,7 @@
+---
+title: CodeTools
+---
+
 An overview of tools that will help improve your Go code
 
 ## All-in-one
@@ -67,3 +71,4 @@ An overview of tools that will help improve your Go code
 ## Visualization
 
   - [godepgraph](http://github.com/kisielk/godepgraph) - A tool for generating dependency graphs of Go code.
+